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

No annotations are present, so the description bears the burden. It discloses synchronous execution and return content, and mentions parameters like allow_write and sandbox that hint at side-effect control, but it does not specify permissions, side effects, or operational risks.

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 two sentences, efficiently delivering the core action, return type, and parameter compatibility. No filler or redundancy; information is front-loaded.

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 15 parameters, 0% schema coverage, and no annotations, the description is too thin. It relies heavily on familiarity with the legacy gemini tool and does not explain modes, enums, or the output structure beyond 'assistant text + metadata'.

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. It lists parameter groups ('same PROMPT / cd / ...' and 'new mode / timeout / ...') but does not explain the meaning of individual parameters or enum values, leaving the agent without sufficient semantics.

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 explicitly states 'Run agy --print synchronously and return the assistant text + metadata', providing a specific verb, resource, and output. It distinguishes this from sibling tools like agy_start and agy_continue by positioning it as the primary execution tool.

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

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

The description offers clear context by calling itself a 'drop-in for the legacy gemini tool', indicating when it should be used (when you would use gemini). However, it does not explicitly contrast with siblings or provide exclusions, but the inference is straightforward from the names.

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?

No annotations are provided, so the description must carry behavioral disclosure. It adds meaningful outcome semantics (signalled=True if the worker was alive, False if unknown or already finished), but omits permissions, whether cancellation is guaranteed or graceful, and 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.

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

Two tightly written sentences with purpose front-loaded and outcome details second. No filler; every sentence contributes.

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

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

For a single-parameter tool with an output schema, the description covers purpose, accepted identifier forms, and outcome meaning. It lacks permission/ownership requirements and prefix-ambiguity behavior, but is nearly complete for correct invocation.

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

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

Schema description coverage is 0% and the sole job_id parameter has no schema description. The description compensates by stating it accepts a full job_id or a unique prefix, adding important input semantics, though it does not address prefix-ambiguity handling.

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 ('Signal ... to stop') and resource ('running job'), and explains accepted identifier forms. However, it does not distinguish this tool from siblings like agy_status or agy_read, so it is clear but lacks explicit sibling differentiation.

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 explicit when-to-use guidance versus alternatives such as agy_status; the only context is the implied 'running job' condition. No prerequisites or exclusions are stated, matching the calibration example for a tool that lacks usage guidance.

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?

No annotations are provided, so the description must disclose behavioral traits but only says 'the underlying adapter resumes the Antigravity conversation.' It does not mention side effects, write permissions, session state changes, or other behaviors. Given zero annotation coverage, this is a significant 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 sentences, front-loaded with the core purpose, and every word adds value. It efficiently conveys the main function and the critical requirement (SESSION_ID) without redundancy.

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

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

Despite having an output schema, the tool has 15 parameters and no annotations. The description is minimal and does not explain key behavioral aspects like modes, backends, or the meaning of parameters such as allow_write or return_all_messages. It is too sparse for a tool of this complexity.

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 only adds meaning to SESSION_ID (clarifying it is required for continuation). It does not explain PROMPT or the other 13 parameters, nor does it elaborate on enums or defaults. The reference to `agy` might imply shared semantics, but that is not self-contained.

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 explicitly states 'Continue an existing agy session' with a specific verb and resource, and distinguishes itself from siblings by noting 'Identical to `agy` except SESSION_ID is required.' This clearly differentiates it from agy_start (new session) and other session-related 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?

It implies usage is for continuing an existing session, with 'SESSION_ID is required' as the key differentiator. It references the alternative `agy` but does not explicitly state exclusions like 'do not use for new sessions.' However, the context is clear enough for an agent to decide when 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?

With no annotations, the description takes on the burden. It discloses caching behavior ('drop the cached binary probe'), the return format ('structured report (no secrets)'), and appropriateness for MCP. It doesn't explicitly state safety or side effects, but the context is adequate.

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 concise sentences front-load the purpose, describe the output, and then explain the parameter. No wasted words.

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

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

The tool is simple (one optional parameter) and an output schema exists. The description covers the purpose, output nature, and the cache nuance, making it complete for an agent to invoke correctly.

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

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

Despite 0% schema coverage, the description fully explains the one parameter: 'Pass `force_refresh=true` to drop the cached binary probe' and gives the exact scenario for using it.

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

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

The description states 'Run capability + auth + session-store probes' with a specific verb and resource, clearly distinguishing it from sibling tools like agy_status or agy_read as a diagnostic tool.

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

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

It provides clear context for the force_refresh parameter ('use after upgrading the underlying agy / gemini CLI'), but does not explicitly compare with alternatives or state when-not to use it. The diagnostic purpose is 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?

With no annotations, the description fully bears the transparency burden. It details exact filesystem paths per scope, the force flag behavior (skip vs. unconditional rewrite), and the reasoning behind using ~/.agy/ over ~/.gemini/ due to a standing rule. This is 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?

The description is a single well-structured paragraph, front-loaded with the main action, then logically covering targets, scope paths, the Antigravity exception, and force semantics. Every sentence adds necessary context without waste.

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 4 parameters, 0% schema coverage, and existing output schema, the description covers all parameters, defaults, and edge cases, leaving no significant ambiguity for an agent to decide when and how to 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 description compensates thoroughly: targets values are enumerated, scope modes are tied to concrete paths, project_root is explained, and force behavior is defined for both false and true.

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 opens with a specific verb+resource: 'Install the agy-mcp collaboration skill bundle into one or more agent platforms.' It clearly differentiates from sibling tools like agy_start or agy_status by focusing on installation.

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 explains target expansion and scope semantics, giving clear context on parameter choices. It does not explicitly name alternatives or exclusions, but the tool's purpose is self-contained and sibling names clearly differ.

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?

With no annotations provided, the description carries the full burden. It discloses the deletion action, the validation constraints (positive integer <= 3650, rejection of zero/negative), and the return value (removed job ids and coarse count). This adds safety context and expected behavior, though it does not detail irreversible effects or permissions.

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 two sentences with no redundancy. The first sentence states the core action, the second provides validation details and rationale. Every word adds value, and the most critical information is front-loaded.

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?

The description covers the tool's purpose, parameter constraints, and return value, which is sufficient given the simple single-parameter interface and the presence of an output schema. It does not describe the exact structure of the output, but the output schema presumably covers that, and it does not mention edge cases like empty results, but these are minor gaps.

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 schema only defines `days` as an integer with a default, providing no description. The tool description fills this gap completely by specifying the valid range (1-3650), the requirement for positivity, and the rationale for rejecting zero/negative values, which prevents misuse.

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 clearly states the action ('Delete') and the resource ('session-store job directories'), and specifies the condition based on mtime and days. It also mentions the return value, which distinguishes it from sibling tools like agy_status or agy_cancel by describing a unique cleanup operation.

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 usage for cleaning up old session jobs, and explicitly warns about safe values for `days` to avoid accidental wipes. However, it does not explicitly state when to prefer this tool over alternatives, nor does it mention when not to use it (e.g., if active jobs might be affected).

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?

With no annotations, the description carries the full behavioral burden. It does disclose useful operational detail (since is a 0-based offset, the default return is canonical event dicts, job_id accepts a unique prefix), but it says nothing about whether reads are non-destructive, whether the call blocks waiting for new events, or whether a cursor/offset is persisted across calls.

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 compact clauses, purpose front-loaded, then per-parameter clarifications in the order the agent will encounter them. No filler sentences.

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

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

The output schema exists, so return values needn't be documented. However, for a polling-style log-read tool with no annotations and many confusable siblings, the description should have covered whether the read blocks, whether it is safe/repeatable, and how it relates to agy_result/agy_status. Those gaps leave the agent under-informed.

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% (titles only), so the description must carry the load, and it documents all three parameters: the meaning and base of `since`, the accepted `translate` values with the default behavior spelled out, and the prefix-matching rule for `job_id`. It stops short of explaining how the raw/claude/codex wire formats differ, keeping it from a 5.

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 first sentence gives a specific verb and resource: 'Read events from a job's event log.' That is unambiguous about what the tool does. What it lacks is any differentiation from siblings such as agy_result or agy_status, which an agent must distinguish to pick the right tool.

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, when-not-to-use, or alternative-tool guidance. Nothing tells the agent whether to call agy_read versus agy_result (for results) or agy_status (for state), so selection rests entirely on inferring from the name.

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

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

With no annotations, the description carries the full behavioral burden. It does useful work: it implies a read-only retrieval, defines the default (latest finished job from agy_sessions), and clarifies the include_events toggle. However it never states failure modes — what happens if the job is still running, if the prefix matches multiple jobs, or if no finished job exists — which matters for a tool whose whole contract is id selection.

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 the core action before the argument-selection rules. Slightly dense in the second sentence, but no filler and every clause carries routing 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?

An output schema exists, so return values need no explanation, and the core invocation paths are covered. Still incomplete for a job-selection tool: 'since' semantics and the behavior on ambiguous or non-finished job ids are unresolved, so an agent could call it correctly but not predict its edge-case behavior.

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. It does explain job_id (full id or unique prefix) and include_events (returns stored events), but the 'since' parameter is entirely undocumented in both the schema and the description, leaving one of three parameters opaque.

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 ('Return the captured output for a finished background job') with the scope qualifier 'finished'. It explicitly distinguishes itself from siblings by naming agy_read and agy_sessions, so an agent can route between them 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?

Gives explicit selection rules: pass job_id (full or unique prefix) to target a job, omit it to fall back to the latest finished job from agy_sessions. It also names the alternative path for full event retrieval ('otherwise use agy_read'), which is exactly the when-to-use/when-to-use-something-else guidance the dimension asks for.

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?

With no annotations, the description carries the full burden. It discloses the ordering ('newest first') and the limit behavior (default 50, 0 for full list), which is useful. However, it does not explicitly state that the operation is read-only or describe potential side effects, though 'list' implies a safe read.

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 entire description is a single sentence, concise and front-loaded with the main action. Every word earns its place, conveying both purpose and parameter details without fluff.

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 list tool with one optional parameter and an output schema, the description covers the core aspects: what is listed, ordering, and limit semantics. It omits explicit mention of read-only status or the definition of 'jobs', but the presence of an output schema reduces the need to describe 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?

The schema provides only a bare parameter with a default, but the description adds crucial semantics: 'limit defaults to 50; pass 0 for the full list.' This explains the parameter's behavior and special value, effectively compensating for the 0% schema description coverage.

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 clearly states the tool 'List recent jobs' with an explicit ordering ('newest first'), giving a specific verb and resource. It does not explicitly differentiate from sibling tools like agy_status or agy_result, but the resource 'jobs' and the list action are distinct enough.

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 provides no guidance on when to use this tool versus alternatives such as agy_status or agy_result. There is no mention of typical use cases, prerequisites, or exclusions, leaving the agent without context for tool selection.

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?

With no annotations, the description must carry the burden of behavioral disclosure. It discloses that the session runs in the background and returns a status and job_id. It does not mention side effects like file system changes, permissions, or rate limits, but for a 'start' tool the core behavior is reasonably conveyed. Lacks depth expected for a 14-parameter tool.

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

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

Two sentences, front-loaded, zero fluff. The first sentence states the core action, the second explains the return value and next steps. Every word earns its place.

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

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

Despite the presence of an output schema (per context), the tool is complex with 14 parameters and rich options (modes, sandbox, workflows). The description only covers the basic launch-and-poll flow, offering almost no guidance on parameter selection, which is essential for correct usage in varied situations.

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 should compensate for parameter meaning. It does not explain any of the 14 parameters (PROMPT, mode, backend, sandbox, allow_write, etc.). The only mention of job_id refers to the return value, not the input parameter. This leaves the agent guessing about all parameters.

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 clearly states the tool's action: 'Start an agy session in the background.' This identifies a specific verb and resource, and the mention of returning a job_id to poll distinguishes it from sibling tools like agy_status and agy_cancel. It leaves no ambiguity about what the tool does.

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 provides clear context: this tool is for launching a background session and then polling it via agy_status/agy_read/agy_cancel. It implies usage for asynchronous workflows and names the related tools. However, it does not explicitly say when NOT to use this tool or mention alternatives like 'agy' for interactive sessions.

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?

No annotations are supplied, so the description carries the full burden. It usefully enumerates the returned record contents (status, exit code, error, timestamps), but never states that this is a read-only, non-mutating operation, nor any auth, rate-limit, or polling behavior for a status-check tool.

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

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

A single front-loaded sentence with no filler; the returned fields are parenthesized rather than expanded, and the input rule is stated compactly. 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?

The output schema already covers return values, so restating them is harmless but not the missing piece. What is missing is sibling disambiguation and the read-only safety profile — the two things an agent actually needs to choose and safely call this among agy_start, agy_result, and agy_read.

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, and it does: it discloses that job_id may be a full id OR a unique job-id prefix, which is non-obvious behavior absent from the schema's plain 'Job Id' string. It stops short of giving format details or stating what happens on an ambiguous prefix.

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 ('Return') and a specific resource ('the JobRecord') scoped to a job, which is clearer than the bare name agy_status. However, it does nothing to differentiate itself from close siblings like agy_result, agy_read, or agy_sessions, so an agent cannot route between them from this text alone.

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 says what input it takes but never states when to call this versus agy_result, agy_read, or agy_continue. There are no exclusions, prerequisites, or contextual triggers, leaving the agent to guess at routing among a crowded sibling set.

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