Server Quality Checklist

Tool Scores

• invoker_add_environmentA
  3.5/5.0
  Behavior3/5

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

  Annotations indicate readOnlyHint=false, consistent with the 'Create' action implying a mutation. The description adds that variables are optional, which is useful context beyond annotations. However, it lacks details on permissions, side effects (e.g., if environment names must be unique), or error conditions, leaving behavioral gaps.

  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 a single, efficient sentence that front-loads the core purpose ('Create a new environment') and adds a concise qualifier ('with optional initial variables'). Every word earns its place with no redundancy or unnecessary elaboration.

  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 creation tool with no output schema and minimal annotations, the description is adequate but incomplete. It covers the basic action and optional parameters, but lacks information on return values, error handling, or dependencies with sibling tools, leaving the agent with gaps in understanding the full context.

  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 clear descriptions for both parameters in the schema itself. The description mentions 'optional initial variables', aligning with the schema but not adding significant meaning beyond it. No additional syntax, constraints, or examples are provided in the description.

  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 action ('Create') and resource ('new environment'), with the optional 'initial variables' providing specific detail about what can be configured. It distinguishes from siblings like 'invoker_list_environments' (list vs create) and 'invoker_set_variable' (set variable vs create environment with variables), though not explicitly named.

  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 for creating environments, but provides no explicit guidance on when to use this versus alternatives like 'invoker_switch_environment' or 'invoker_set_variable', nor any prerequisites or constraints. The optional nature of variables is mentioned, but no broader context is given.

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

• invoker_create_requestA
  3.8/5.0
  Behavior3/5

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

  Annotations indicate this is not read-only and not destructive, which aligns with the description's 'create' action. The description adds useful context by specifying that the file is written to disk, but does not disclose additional behavioral traits like error handling, file overwriting behavior, or format specifics beyond .ivk. With annotations covering the basic safety profile, this provides moderate value.

  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 a single, well-structured sentence that front-loads the core action and efficiently lists optional components. Every word contributes to understanding the tool's function without redundancy or unnecessary elaboration.

  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 creation tool with 11 parameters and no output schema, the description adequately covers the essential action and key inputs. However, it lacks details on the .ivk file format structure, potential side effects (e.g., file overwriting), or example usage, which could help in more complex scenarios. The annotations provide basic safety context, but some behavioral gaps remain.

  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%, so the schema fully documents all 11 parameters. The description mentions key parameters (HTTP method, URL, headers, body, auth, scripts) but adds no syntax or format details beyond what the schema provides. This meets the baseline for high schema coverage without enhancing parameter understanding.

  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 clearly states the specific action ('Create a new .ivk request file') and resource (the file), distinguishing it from sibling tools like invoker_read_request or invoker_send_request. It specifies the file format (.ivk) and key components to include, making the purpose unambiguous.

  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 for creating request files, but does not explicitly state when to use this tool versus alternatives like invoker_send_request (for executing requests) or invoker_read_request (for reading existing files). No exclusions or prerequisites are mentioned, leaving some ambiguity about the appropriate context.

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

• invoker_set_variableA
  4/5.0
  Behavior4/5

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

  Annotations indicate readOnlyHint=false (mutation) and idempotentHint=true (safe to retry). The description adds valuable context beyond this: it specifies that the variable is set 'in the active environment' (scope) and will be used 'to resolve {{name}} placeholders in subsequent requests' (behavioral impact). This clarifies persistence and usage without contradicting annotations, though it doesn't mention rate limits or auth needs.

  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 two sentences that are front-loaded with the core action and efficiently explain the purpose and impact. Every sentence earns its place: the first defines the tool, and the second clarifies its utility, with zero wasted words or redundancy.

  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?

  Given the tool's moderate complexity (mutation with idempotency), annotations cover safety aspects, and schema fully documents inputs. The description adds necessary context about the active environment and placeholder resolution. However, without an output schema, it doesn't describe return values (e.g., success confirmation), leaving a minor gap. Overall, it's mostly complete for the given structured data.

  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 clear descriptions for 'name' and 'value' parameters. The description does not add any additional meaning beyond the schema (e.g., no format constraints or examples for placeholders). Since the schema already fully documents the parameters, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

  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 clearly states the specific action ('Set an environment variable') and the target resource ('in the active environment'), distinguishing it from siblings like 'invoker_add_environment' (which likely adds a new environment) or 'invoker_switch_environment' (which changes the active environment). It also explains the purpose ('used to resolve {{name}} placeholders in subsequent requests'), making the verb+resource+scope explicit.

  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 by mentioning 'active environment' and 'subsequent requests', suggesting it should be used when configuring variables for future operations. However, it does not explicitly state when to use this tool versus alternatives (e.g., vs. 'invoker_add_environment' for environment-level changes) or any exclusions (e.g., not for temporary variables). The guidance is contextual but lacks explicit alternatives or when-not-to-use details.

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

• invoker_build_siteA
  4.2/5.0
  Behavior4/5

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

  Annotations indicate readOnlyHint=false and destructiveHint=false, which the description does not contradict. The description adds valuable behavioral context beyond annotations by specifying the output ('Produces a deployable dist/'), the content types generated ('markdown docs and inline runnable .ivk request widgets'), and a prerequisite ('Requires the invoker-app to be installed'), enhancing the agent's understanding of the tool's behavior and requirements.

  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 concise and well-structured, consisting of two sentences that efficiently convey the tool's purpose, output, and prerequisite without unnecessary details. The first sentence explains what the tool does and what it produces, while the second sentence adds a critical requirement, making every sentence earn its place.

  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?

  Given the tool's complexity (building a documentation site with multiple parameters) and the absence of an output schema, the description is mostly complete. It covers the purpose, output, and prerequisites, but does not detail the return values or error handling, which could be useful for an agent. However, with annotations providing safety hints and the schema covering parameters, the description is sufficient for effective use.

  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, with clear documentation for all three parameters (collection_path, output_path, title). The description does not add any additional semantic details about the parameters beyond what the schema provides, such as explaining the structure of the collection folder or the format of the output. This meets the baseline of 3 since the schema adequately covers parameter information.

  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 clearly states the specific action ('Build a static documentation site'), the resource ('from an Invoker collection folder'), and the output ('Produces a deployable dist/ with markdown docs and inline runnable .ivk request widgets'). It distinguishes itself from sibling tools like invoker_list_collection or invoker_send_request by focusing on site generation rather than collection management or request execution.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use this tool ('Build a static documentation site from an Invoker collection folder') and includes a prerequisite ('Requires the invoker-app to be installed'), which helps guide usage. However, it does not explicitly state when not to use it or mention alternatives among the sibling tools, such as invoker_list_collection for viewing collections instead of building sites.

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

• invoker_list_collectionA
  4.2/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=true, which the description aligns with by describing a scanning/discovery operation. The description adds valuable behavioral context beyond annotations by specifying what file types are scanned (.ivk and .md), what is returned (file tree with counts), and the tool's purpose (discovery), without contradicting the read-only annotation.

  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 front-loaded with the core action and purpose in two concise sentences, with no wasted words. Each sentence earns its place by defining the operation and its usage context efficiently.

  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?

  Given the tool's low complexity (1 parameter, read-only, no output schema), the description is mostly complete by covering purpose, usage, and behavioral details. However, it lacks information on output structure (e.g., format of the 'file tree with counts'), which would be helpful since there is no output schema.

  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 the parameter 'folder_path' fully documented in the schema. The description does not add additional meaning or details about the parameter beyond what the schema provides, such as examples or constraints, so it meets the baseline score of 3.

  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 clearly states the specific action ('Scan a folder for .ivk request files and .md documentation files') and resource ('collection folder'), distinguishing it from siblings like 'invoker_read_request' or 'invoker_send_request' which operate on individual requests rather than scanning folders for collections.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use this tool ('Use this to discover what requests and docs exist in a collection'), but does not explicitly state when not to use it or name specific alternatives among the sibling tools, such as 'invoker_list_environments' for environment discovery instead.

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

• invoker_read_requestA
  4.2/5.0
  Behavior3/5

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

  The annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds useful context by specifying that it returns parsed request details (method, URL, headers, etc.), which clarifies the output behavior. However, it doesn't mention potential errors (e.g., file not found) or parsing limitations, leaving some behavioral aspects uncovered.

  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 two sentences that are front-loaded with the core purpose and followed by usage guidance. Every word contributes directly to understanding the tool's function and when to use it, with no redundant or unnecessary information.

  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 read-only tool with one well-documented parameter and no output schema, the description is mostly complete: it explains the purpose, usage context, and return content. However, it lacks details on error handling or output structure (though the absence of an output schema makes this less critical), leaving a minor gap.

  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, with the single parameter 'file_path' clearly documented as 'Path to the .ivk file'. The description doesn't add any additional semantic details about the parameter beyond what the schema provides, so it meets the baseline for high schema coverage without extra value.

  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 clearly states the specific action ('Read and parse an .ivk file') and the resource ('.ivk file'), distinguishing it from siblings like 'invoker_send_request' (which sends requests) and 'invoker_create_request' (which creates them). It explicitly mentions what the tool returns (parsed request details), making the purpose unambiguous.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool ('to inspect what a request does before sending it'), directly contrasting it with 'invoker_send_request' (which sends the request). This helps the agent choose between reading/parsing versus executing actions, offering clear alternatives.

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

• invoker_send_requestA
  4.2/5.0
  Behavior4/5

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

  Annotations indicate this is a mutable operation (readOnlyHint: false) with open-world behavior (openWorldHint: true). The description adds valuable behavioral context beyond annotations: it discloses variable resolution from active environment, pre/post script execution, and comprehensive response details (status, headers, body, test results, console logs), which are not captured in 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 efficiently structured in a single sentence that front-loads the core purpose and follows with key behavioral details. Every element (variable resolution, scripting, response components) earns its place without redundancy or unnecessary elaboration.

  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?

  Given the tool's complexity (HTTP execution with scripting and variable resolution), no output schema, and rich annotations, the description provides substantial context about behavior and return values. However, it doesn't address potential side effects, error handling, or authentication requirements that might be relevant for a mutable, open-world tool.

  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, the schema fully documents all 5 parameters. The description adds minimal parameter semantics beyond the schema, mentioning the file_path vs. inline params dichotomy but not providing additional syntax, format, or constraint details. This meets the baseline for high schema coverage.

  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 clearly states the specific action ('Execute an HTTP request') and resources ('.ivk file or inline params'), distinguishing it from siblings like invoker_create_request (creation) or invoker_read_request (reading). It specifies the verb+resource combination precisely.

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

  Usage Guidelines4/5

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

  The description provides clear context for usage (executing HTTP requests with environment variable resolution and scripting), but doesn't explicitly state when NOT to use it or name specific alternatives among siblings. It implies usage through functional description rather than comparative guidance.

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

• invoker_switch_environmentA
  4.2/5.0
  Behavior4/5

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

  Annotations indicate readOnlyHint=false and idempotentHint=true, but the description adds valuable context beyond this: it specifies that the switch affects 'All subsequent variable resolution,' implying a state change with downstream effects. This clarifies behavioral traits not covered by annotations, such as the tool's impact on future operations, though it doesn't detail error handling or validation specifics.

  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 front-loaded and concise, consisting of two sentences that directly convey the tool's action and its immediate effect. Every sentence earns its place by adding critical information without redundancy, making it efficient and well-structured for quick understanding.

  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?

  Given the tool's moderate complexity (state-changing with one parameter) and the absence of an output schema, the description is largely complete: it explains the purpose, usage, and behavioral impact. However, it lacks details on potential errors (e.g., invalid environment names) or confirmation of success, which could enhance completeness for a mutation tool without output schema.

  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, with the 'environment' parameter documented as accepting a name or numeric index. The description adds minimal semantic value beyond this, only restating that it's 'by name or index.' Since the schema already covers this thoroughly, the baseline score of 3 is appropriate, as the description doesn't provide additional insights like examples or constraints.

  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 clearly states the specific action ('Switch the active environment') and the resource ('environment'), distinguishing it from siblings like 'invoker_list_environments' (which lists) or 'invoker_add_environment' (which adds). It explicitly mentions the effect on variable resolution, making the purpose distinct and comprehensive.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use this tool ('All subsequent variable resolution will use the new environment's values'), indicating it's for changing the active environment. However, it does not explicitly state when not to use it or name alternatives, such as using 'invoker_list_environments' to check available environments first, which prevents a perfect score.

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

• invoker_list_environmentsA
  4.6/5.0
  Behavior4/5

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

  The annotation 'readOnlyHint: true' already indicates this is a safe read operation. The description adds valuable context beyond this by specifying what information is returned (environments with variables, active status) and the tool's purpose in the workflow (to see environments before other actions). It doesn't contradict annotations and provides useful behavioral insight.

  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 two sentences that are front-loaded with the core purpose and followed by clear usage guidance. Every word earns its place, with no redundancy or wasted information, making it highly efficient and well-structured.

  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?

  Given the tool's simplicity (0 parameters, read-only annotation, no output schema), the description is complete enough for an agent to understand its purpose and usage. It covers what the tool does, when to use it, and how it fits with siblings. The lack of output schema is mitigated by the clear description of returned information.

  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 has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing instead on the tool's purpose and usage. This meets the baseline of 4 for tools with no parameters.

  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 clearly states the specific action ('List all environments with their variables') and resource ('environments'), and distinguishes it from siblings by mentioning its role in showing available environments before using tools like 'invoker_switch_environment' or 'invoker_set_variable'. It goes beyond the title by specifying what information is included (variables, active status).

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

  Usage Guidelines5/5

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

  The description explicitly states when to use this tool ('Use this to see available environments before switching or setting variables'), providing clear context and distinguishing it from alternatives like 'invoker_switch_environment' or 'invoker_set_variable'. It effectively guides the agent on the tool's role in the workflow.

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