Server Quality Checklist

Tool Scores

• create_taskC
  2.3/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure but fails to mention key traits: whether the tool returns the created task ID, if it validates UUIDs in the 'depends' array, or what happens if the specified project doesn't exist. It does not disclose mutation side effects beyond the implied creation.

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

  Conciseness3/5

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

  The description is extremely brief (four words), avoiding verbosity. However, it is so minimal that it borders on under-specification rather than efficient conciseness. It is front-loaded but fails to maximize value per sentence.

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

  Completeness2/5

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

  For a tool with 9 parameters including complex date fields and dependency arrays, and no output schema provided, the description is inadequate. It omits what the tool returns upon success (e.g., task ID), error handling behavior, and any Taskwarrior-specific context that would aid an agent in invocation.

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

  Parameters3/5

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

  Schema description coverage is 100%, with all 9 parameters adequately documented in the schema itself. The description adds no supplementary parameter semantics (e.g., syntax examples, validation rules), but the baseline score of 3 applies when schema coverage is high and the schema does the heavy lifting.

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

  Purpose2/5

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

  The description 'Create a new task' essentially restates the tool name (create_task), constituting a tautology. While it identifies the verb and resource, it fails to distinguish this tool from siblings like update_task or annotate_task, and does not clarify the scope or nature of the task being created.

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

  Usage Guidelines2/5

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

  No guidance is provided on when to use this tool versus alternatives such as update_task, or prerequisites like ensuring dependencies exist. The description lacks explicit when-to-use or when-not-to-use conditions.

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

• get_taskB
  3.1/5.0
  Behavior2/5

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

  No annotations are provided, so the description must carry the full burden of behavioral disclosure. It fails to indicate whether the operation is read-only, what happens if the ID doesn't exist (404 vs null), or what fields are returned in the response.

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

  Conciseness5/5

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

  Extremely concise at 7 words with zero redundancy. The critical information (single resource, lookup key) is front-loaded and immediately scannable.

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

  Completeness3/5

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

  For a simple CRUD retrieval with one well-documented parameter and no output schema, the description is minimally adequate. However, given the lack of annotations and output schema, it should ideally mention error handling behavior or the nature of the returned data to be fully complete.

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

  Parameters3/5

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

  The input schema has 100% description coverage ('Task ID or UUID'), and the description mirrors this exactly without adding additional semantic context (e.g., format requirements, examples, or whether UUID and ID are interchangeable). Baseline 3 is appropriate when the schema is self-documenting.

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

  Purpose4/5

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

  States the specific action (Get), resource (task), and lookup method (by ID or UUID). The term 'single' effectively distinguishes it from the sibling 'list_tasks'. However, it doesn't explicitly reference sibling tools to clarify the selection boundary.

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

  Usage Guidelines2/5

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

  Provides no explicit guidance on when to use this tool versus alternatives like 'list_tasks' (for searching without an ID) or 'create_task' (when the task doesn't exist). No prerequisites or error conditions are mentioned.

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

• project_listB
  3.2/5.0
  Behavior2/5

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

  With no annotations provided to indicate safety or side effects, the description carries the full burden of behavioral disclosure but offers minimal information. While 'List' implies a read-only operation, the description fails to specify the return format, what constitutes a 'project' in this context, or behavior when no projects exist.

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

  Conciseness5/5

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

  The description consists of a single, efficient six-word sentence with no redundant phrases or filler content. The essential information (action, scope, domain) is front-loaded and immediately accessible.

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

  Completeness3/5

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

  Given the tool's low complexity (zero parameters, no nested objects) and lack of output schema, the description meets minimum viability by identifying the core operation. However, without annotations or return value documentation, the agent lacks critical context about the response format and operational constraints.

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

  Parameters4/5

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

  The input schema contains zero parameters, triggering the baseline score of 4 per evaluation rules. The description does not introduce phantom parameters or create confusion, appropriately matching the empty schema structure.

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

  Purpose4/5

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

  The description uses the specific verb 'List' with the clear resource 'all projects in Taskwarrior', establishing the tool's function effectively. While it correctly identifies the domain (projects) distinct from task-oriented siblings like create_task, it lacks explicit contrastive language to differentiate use cases from similar list operations.

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

  Usage Guidelines2/5

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

  The description provides no explicit guidance on when to invoke this tool versus alternatives, or any prerequisites for its use. Although the tool's simplicity (zero parameters) makes its usage somewhat self-evident, there is no mention of when to prefer this over filtering tasks by project or how it relates to project discovery workflows.

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

• complete_taskB
  3.3/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full disclosure burden. It successfully adds critical behavioral context about the 'auto-claims then releases' mechanism not visible in the schema. However, it omits other essential behavioral traits for a state-mutation tool: whether the operation is idempotent, if 'completing' an already-done task is an error, and what specific side effects occur (notifications, project updates, etc.).

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

  Conciseness5/5

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

  Extremely efficient two-sentence structure with zero redundancy. The first sentence states the primary effect; the second sentence adds the crucial claim/release behavioral detail. Every word earns its place.

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

  Completeness3/5

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

  Given the lack of annotations and output schema, the description provides the minimum viable context for a 2-parameter mutation tool. It explains the action and the transient claim behavior, but leaves gaps regarding error conditions, return values, or the implications of the completion state on related workflows (e.g., dependent tasks).

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

  Parameters3/5

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

  Schema description coverage is 100%, establishing a baseline of 3. The description mentions 'auto-claims' which indirectly hints at the purpose of 'agent_id', but it does not add explicit parameter semantics, validation constraints, or usage examples beyond what the schema already documents for 'id' and 'agent_id'.

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

  Purpose4/5

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

  The description clearly states the core action ('Mark a task as done') with a specific verb and resource. However, it does not differentiate from the sibling 'update_task' tool, which could also potentially modify task status, leaving ambiguity about when to prefer 'complete' over a generic update.

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

  Usage Guidelines2/5

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

  No explicit guidance is provided on when to use this tool versus alternatives (e.g., 'update_task' for partial modifications), nor are prerequisites mentioned (such as task ownership requirements implied by the claim mechanism). The description assumes the agent knows when completion is appropriate.

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

• list_tasksB
  3.3/5.0
  Behavior3/5

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

  Since no annotations are provided, description carries full disclosure burden. It valuably discloses return structure (claim metadata fields: owner_agent, lease_until, etc.), revealing this is a claimed-task system. However, it omits safety properties (read-only?), pagination behavior, or side effects.

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

  Conciseness5/5

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

  Two sentences with zero waste. First sentence establishes purpose and filtering; second sentence discloses return value structure. Information is front-loaded and every clause earns its place.

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

  Completeness3/5

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

  For a 6-parameter tool with no output schema, the description covers basic filtering and return metadata. However, it lacks pagination details, doesn't explain why 'tags' is required (unusual for a list operation), and doesn't describe the array structure or total count of returned results.

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

  Parameters3/5

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

  With 100% schema description coverage, baseline is 3. The description mentions four filter categories (status, project, tags, priority) but misses 'due_before' and 'due_after'. It adds semantic grouping ('optionally filtered') but doesn't compensate for schema limitations or explain the unusual required 'tags' constraint.

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

  Purpose4/5

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

  States specific verb ('List') and resource ('tasks') clearly. Mentions filtering capabilities (status, project, tags, priority) which helps distinguish from sibling 'get_task' (implied single retrieval vs multiple), though it could explicitly clarify 'list' vs 'get' distinction in the text.

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

  Usage Guidelines2/5

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

  No explicit guidance on when to use this versus 'get_task' for single-task retrieval, or when filtering is preferable to fetching all tasks. No mention of prerequisites or performance considerations for large task lists.

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

• update_taskA
  3.5/5.0
  Behavior3/5

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

  No annotations provided, so description carries full burden. It successfully discloses the side effect of auto-claiming, but omits other critical behavioral details like error handling (task not found), idempotency, or whether partial updates are supported.

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

  Conciseness5/5

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

  Two sentences, zero waste. Front-loaded with the core operation, followed immediately by the critical side effect. Every word earns its place.

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

  Completeness3/5

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

  Adequate for basic invocation but incomplete for a 12-parameter mutation tool lacking annotations and output schema. Missing explanation of auto-claim mechanics, the interaction between tags/remove_tags, and error scenarios.

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

  Parameters3/5

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

  Schema has 100% description coverage, establishing baseline 3. The description adds minimal value beyond the schema—mentioning 'fields' generically without clarifying the unusual requirement that tags, remove_tags, and depends are mandatory (requiring empty arrays for no-op).

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

  Purpose4/5

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

  Clear verb ('Update') and resource ('existing task') with specific scope. The 'auto-claims' behavior distinguishes it from sibling tools like annotate_task or complete_task, though it could clarify what 'fields' entails.

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

  Usage Guidelines3/5

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

  The auto-claim behavior provides implicit guidance (use this when taking ownership), but lacks explicit when-to-use comparisons against siblings like create_task or annotate_task, and doesn't warn about the required array parameters.

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

• delete_taskA
  3.6/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully reveals the side-effect behavior (auto-claiming and releasing) that isn't obvious from the schema. However, it fails to explicitly warn that deletion is destructive/permanent, which is critical safety information for a deletion operation without destructiveHint annotations.

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

  Conciseness5/5

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

  The description is optimally concise with two efficient sentences. It front-loads the primary action ('Delete a task') before detailing implementation specifics ('Auto-claims...'). Every word earns its place; there is no redundant or filler text.

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

  Completeness3/5

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

  Given the simple 2-parameter schema with full coverage and no output schema, the description is nearly sufficient. However, for a destructive mutation tool lacking annotations, the description should explicitly state that the operation is irreversible or permanent to meet minimum completeness standards.

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

  Parameters4/5

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

  With 100% schema coverage, the baseline is 3. The description adds semantic value beyond the schema by implying that agent_id is used for the auto-claim mechanism mentioned ('Auto-claims'), giving context for why the agent identifier is required rather than just listing it as a technical requirement.

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

  Purpose4/5

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

  The description clearly states the primary action ('Delete a task') with a specific verb and resource. It distinguishes from sibling tools (create_task, update_task, etc.) by specifying deletion. However, it could strengthen differentiation by explicitly stating this permanently removes the task versus completing or archiving it.

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

  Usage Guidelines3/5

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

  The description implies usage context through the 'Auto-claims then releases' detail, suggesting this handles claiming automatically versus tools that require explicit claiming first. However, it lacks explicit when-to-use guidance (e.g., 'Use this to permanently remove a task rather than completing it') or prerequisites.

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

• start_taskA
  3.8/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden and successfully discloses key behavioral traits: 'auto-claims' indicates ownership mutation and 'sets active timer' reveals side effects on tracking state. However, it omits error scenarios (e.g., already claimed) and idempotency guarantees.

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

  Conciseness5/5

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

  Single sentence with zero waste: the main clause establishes purpose and the parenthetical adds critical behavioral differentiation. Every word earns its place with no filler or redundant explanations.

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

  Completeness4/5

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

  For a two-parameter tool without output schema, the description adequately covers the core operation and primary side effects. It appropriately omits return value details (no output schema exists), though it could strengthen completeness by noting error conditions or claim collision behavior.

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

  Parameters3/5

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

  Schema description coverage is 100%, establishing a baseline of 3. The description implies the purpose of parameters (needing an ID to start work and implicit agent identity for claiming) but does not explicitly elaborate on parameter semantics, formats, or constraints beyond what the schema already provides.

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

  Purpose5/5

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

  The description provides a specific verb ('Start working') and resource ('task'), with the parenthetical clearly distinguishing this from sibling tools like create_task or update_task by specifying it 'auto-claims and sets active timer'—revealing this is about work session initiation, not just status modification.

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

  Usage Guidelines2/5

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

  While 'Start working' implies the general context, the description lacks explicit guidance on when to use this versus siblings (stop_task, complete_task) or prerequisites (e.g., task existence, claim availability). No 'when-not' conditions or alternative recommendations are provided.

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

• annotate_taskA
  4/5.0
  Behavior4/5

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

  No annotations provided, but description carries burden well by disclosing critical side effects: 'auto-claims, renews lease'. Missing details on failure modes, return values, or idempotency, but the side-effect disclosure is valuable.

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

  Conciseness5/5

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

  Extremely concise (11 words). Front-loaded with action verb. Every element earns its place: action, synonym clarification, target, and critical side effects in parentheses. Zero waste.

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

  Completeness4/5

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

  Good coverage for a 3-parameter mutation tool: explains action and side effects. Lacks description of return value or success/failure behavior (no output schema exists to guide this), but the core behavioral disclosure compensates partially.

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

  Parameters3/5

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

  Schema has 100% description coverage (id, agent_id, annotation all documented). Description doesn't add parameter-specific semantics beyond schema, which is acceptable baseline when schema coverage is high. No additional syntax or format guidance provided.

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

  Purpose5/5

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

  Clear specific verb ('Add') with resource ('annotation/note') and target ('task'). Distinct from siblings like update_task (general fields) and create_task (new tasks). The parenthetical side-effects further clarify unique behavior.

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

  Usage Guidelines3/5

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

  Implies usage for adding notes to existing tasks, but lacks explicit when-to-use vs alternatives (particularly update_task which may handle general task modifications). No explicit exclusions or prerequisites mentioned.

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

• stop_taskA
  4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full disclosure burden. It successfully reveals that the operation pauses the timer and preserves the claim (ownership), providing necessary behavioral context beyond the schema. Minor gap: doesn't address idempotency or error states.

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

  Conciseness5/5

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

  Exemplary conciseness: single sentence with front-loaded action and parenthetical clarification. Every word earns its place; zero redundancy despite conveying distinct behavioral traits.

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

  Completeness4/5

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

  For a 2-parameter state-change tool with no output schema, the description adequately covers the operation's effect (paused timer, retained claim). Sibling context implies this is the inverse of start_task; description is sufficient for correct invocation.

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

  Parameters3/5

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

  Schema description coverage is 100% (both id and agent_id fully documented), establishing baseline 3. The tool description adds no parameter details, but doesn't need to given comprehensive schema documentation.

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

  Purpose5/5

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

  Description provides specific verb (stop), resource (task), and critical behavioral differentiators in parentheses (pauses timer, keeps claim). The 'keeps claim' clause effectively distinguishes it from sibling complete_task.

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

  Usage Guidelines3/5

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

  The parenthetical '(pauses active timer, keeps claim)' implies usage context by distinguishing from complete_task, but lacks explicit 'when to use vs alternatives' guidance. No explicit prerequisites or exclusions stated.

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