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

No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It only states the purpose and does not mention whether the operation is read-only, what specific information is returned, or any potential side effects or prerequisites. While 'get' suggests a read, the description lacks explicit 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, concise sentence with no extraneous content. It is front-loaded with the verb 'Get' and the resource, making it immediately scannable.

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 get operation with one parameter and no output schema, the description is minimal but adequate. However, 'detailed information' is vague and does not hint at the return structure or fields. Given the lack of annotations and output schema, a bit more context about what details are included would improve completeness.

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 100% with database_id described as 'Autonomous Database OCID'. The tool description adds no additional meaning beyond the schema, so the baseline of 3 applies. It does not clarify format, required format, or how to obtain the OCID.

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 'Get detailed information about an Autonomous Database' clearly specifies the verb (get), resource (Autonomous Database), and level of detail. It distinguishes itself from sibling tools like oci_adb_list, which presumably lists databases, and oci_adb_start/stop, which perform actions.

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 does not explicitly state when to use this tool versus alternatives. However, the phrasing 'Get detailed information' implies usage when detailed information about a specific database is needed, contrasting with list operations. No exclusions 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.

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

With no annotations, the description must carry the behavioral burden. 'List' clearly indicates a read-only operation, and the Free Tier note adds useful context about resource limits, but the description does not disclose return format, pagination, or auth needs. This is acceptable for a simple read-only list tool but not fully transparent.

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 short sentences, front-loaded with the core purpose. The Free Tier sentence adds context without being verbose; there is no wasted text.

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 with two optional, fully documented parameters and no output schema. The description states the main purpose and provides relevant context about Free Tier limits, which is sufficient for a list operation. Missing return format details are not critical here.

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 input schema already provides full descriptions for both parameters (limit and compartment_id), so the description adds no parameter-specific meaning. Baseline 3 is appropriate because the schema does the heavy lifting.

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 uses the specific verb 'List' plus the resource 'Autonomous Databases (ATP/ADW)', making it immediately clear what the tool does. This also distinguishes it from sibling tools like oci_adb_get, oci_adb_start, and oci_adb_stop.

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 states what the tool does but gives no explicit guidance on when to use it versus alternatives such as oci_adb_get. It does not mention any exclusions or prerequisites, leaving the usage context 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?

No annotations are provided, so the description must disclose behavioral traits. It only states 'Start a stopped Autonomous Database' without mentioning side effects, async behavior, permission requirements, or what happens if the database is not stopped. This leaves the agent without critical 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, concise sentence: 'Start a stopped Autonomous Database'. It is front-loaded with the action and resource, contains no fluff, and 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?

Given the lack of annotations, no output schema, and only one parameter, the description is minimal. It does not mention prerequisites (e.g., the database must be stopped), expected outcomes, or return values, which are important for a state-changing operation. This leaves the description incomplete for an agent to fully understand the tool's 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?

The schema has 100% coverage for the single parameter database_id, described as 'Autonomous Database OCID'. The description adds no parameter-specific meaning, so the baseline score of 3 applies because the schema already fully documents the parameter.

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 uses the specific verb 'start' with the resource 'Autonomous Database', clearly indicating the tool's function. This distinguishes it from siblings like oci_adb_stop and oci_adb_get, which share the same resource but different actions.

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—when a stopped Autonomous Database needs to be started—but does not explicitly state when to use it versus alternatives such as oci_adb_stop, nor does it mention prerequisites or constraints. This is implied usage rather than explicit 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?

With no annotations, the description is the sole source of behavioral disclosure. It only states the action 'Stop a running Autonomous Database' without elaborating on side effects (e.g., downtime), permission requirements, reversibility, or whether the operation is asynchronous. This falls short of the full burden expected from a mutation 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?

The description is a single, concise sentence that directly states the tool's purpose with no filler or redundancy. It is perfectly 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?

Given the tool's simplicity—one well-documented parameter and no output schema—the minimal description is largely sufficient. However, it could be enhanced by a note about reversibility (e.g., start again with oci_adb_start), but this is not essential given the low 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?

The input schema fully documents the only parameter, database_id, with 'Autonomous Database OCID'. The description does not add any additional semantic detail, but since schema coverage is 100%, the baseline of 3 is appropriate.

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 uses a specific verb 'Stop' and resource 'Autonomous Database', clearly distinguishing it from sibling actions like start, get, and list. It is not a tautology and immediately conveys the tool's function.

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 explicit guidance on when to use this tool versus alternatives. There is no mention of the sibling oci_adb_start or any exclusions, leaving the usage to be inferred from the verb 'stop'.

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 of behavioral disclosure. It implies a read-only list operation but does not state pagination behavior, permission requirements, or what is returned. There is no mention of any side effects, so it is not misleading, but it lacks useful behavioral context beyond the obvious.

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 sentence of seven words, which is extremely concise and front-loaded. It communicates the core action and scope without any filler or redundancy. This is an appropriate size for a simple list operation.

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 no output schema and no annotations, the description is too sparse to be complete. It does not explain return values, pagination via the limit parameter, or how this tool relates to siblings like oci_bv_list_volumes. The tool has three optional parameters, but the description does not clarify how they interact or whether any are required in practice. More context would be needed for an agent to invoke it effectively.

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 100%, so all three parameters have descriptions in the schema. The description adds no extra meaning beyond what the schema already provides. The mention of 'availability domain' in the description simply mirrors the parameter, so the baseline of 3 applies.

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 'List boot volumes in an availability domain' with a specific verb and resource. It mentions the scope (availability domain), which distinguishes it from a general volume listing, but it does not explicitly differentiate from the sibling tool oci_bv_list_volumes. The name itself clarifies boot vs block volumes, so the purpose is clear though not fully distinguished from siblings.

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. It does not mention that oci_bv_list_volumes should be used for block volumes, nor does it explain any prerequisites or intended use cases. The only clue is the mention of availability domain, but that is more of a parameter than 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 carries the burden. The verb 'List' implies a read-only operation, which is the primary behavioral trait, but it does not disclose pagination behavior, default settings beyond the schema, or any other side effects. The Free Tier note adds a small amount of context about quota.

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 sentence with no wasted words. It front-loads the core purpose and includes a concise parenthetical about the Free Tier. This is appropriately sized and easy to parse.

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

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

For a simple list operation with two optional parameters and no output schema, the description plus schema provides a minimal but functional picture. However, it lacks any note about return format, pagination details beyond the schema, or how this tool relates to similar list tools, leaving the agent to infer some usage context.

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 100%, with both parameters (limit and compartment_id) having descriptions in the schema. The tool description itself adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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 uses the specific verb 'List' with resource 'block volumes' and scoping 'in a compartment', clearly distinguishing it from the sibling tool oci_bv_list_boot_volumes which lists boot volumes. The purpose is immediately clear and unambiguous.

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

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

There is no guidance on when to use this tool versus alternatives such as oci_bv_list_boot_volumes. The 'Free Tier: 200GB total' note provides a capacity hint but does not clarify selection criteria or exclusion conditions.

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 carries the burden. 'Get' implies a read-only operation and 'detailed information' hints at the return, but it does not disclose potential errors, permissions, or exact response shape. For a simple one-parameter get, this is adequate but not rich.

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, short sentence that conveys the essential purpose without waste. 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?

Given the tool's low complexity (1 parameter, no output schema), the description is nearly complete. It clearly states the action and target, though it could benefit from specifying what 'detailed information' includes or error handling. No contradictions or gaps that hinder usage.

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 100% (instance_id described as 'Instance OCID'). The description adds no additional parameter meaning beyond 'specific compute instance', which is already implied by the schema. Baseline of 3 applies.

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 uses a specific verb ('Get') and resource ('compute instance') with a qualifier ('specific'), clearly distinguishing it from sibling tools like oci_compute_list_instances. It unambiguously states the tool's function.

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 the usage context: when you need detailed information about a single, known instance. The word 'specific' contrasts with listing, providing clear context without explicitly naming alternatives or exclusions.

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

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

No annotations are provided, and the description doesn't disclose that these are mutating operations, that they may be asynchronous, or that they require certain instance lifecycle states. It only lists action names, which are already in the schema.

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

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

A single, direct sentence that lists all valid actions. No 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?

The tool is simple, but without annotations or output schema, the description doesn't cover behavioral context like state changes or error conditions. It's adequate for basic selection but lacking depth.

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 covers both parameters fully, so baseline 3. The description adds no extra meaning beyond listing the enum values, which are already in the schema.

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 performs actions on compute instances and enumerates the five supported actions, distinguishing it from list/get tools and from ADB start/stop siblings.

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 when to use it (when an action on a compute instance is needed) by naming the resource and actions, but it doesn't explicitly exclude alternatives or state prerequisites. Clear context, but no exclusions.

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

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

With no annotations, the description carries the behavioral burden. It states it shows VM details (shape, state, availability domain), but doesn't disclose pagination behavior or the impact of the limit parameter, which could mislead an agent expecting 'all' instances without any limit.

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 concise sentences, front-loaded with the primary purpose, no redundant wording. Every sentence 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?

For a simple list tool with well-described parameters and no output schema, the description is mostly complete. It covers the returned details but omits pagination or limit semantics, which would be useful for a complete understanding.

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 100%, so both parameters have descriptions. The tool description adds little beyond the schema, only reinforcing the compartment context. No additional parameter semantics are provided, so baseline 3 is appropriate.

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 lists compute instances in a compartment, with a specific verb (List) and resource (compute instances). It distinguishes from sibling tools like get_instance (single) and list_shapes (shapes) by focusing on instances and mentioning returned details.

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 for when to use the tool (to list instances in a compartment), but does not explicitly mention alternatives or exclusions. However, the scope is well-defined, making the usage obvious among siblings.

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

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

With no annotations, the description must carry the transparency burden. It reveals that the listing includes Always Free shapes and gives specific examples, which is useful. However, it does not disclose return format, pagination behavior, or permission requirements, leaving gaps for an agent deciding whether to call this 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?

The description is a single sentence that is front-loaded with the verb and resource, immediately communicating the tool's core function. The extra detail about Always Free shapes adds value without bloat. 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?

For a simple list tool with only two optional parameters and no output schema, the description is nearly complete. It covers the main purpose and adds specific context about Always Free shapes. However, it omits any mention of the optional parameters, though these are documented in the schema. Given the low complexity, this is sufficient.

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 input schema has 100% coverage for its two parameters, so the baseline is 3. The description adds no parameter-specific context (e.g., how compartment_id or limit affect results), but it doesn't need to because the schema descriptions already cover semantics. It does not detract from clarity.

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 a specific verb ('List') and resource ('available compute shapes'), and distinguishes itself from sibling tools like oci_compute_list_instances by focusing on shapes rather than instances. It also adds useful detail about Always Free shapes, making the purpose unmistakable.

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 guidance is given about when to use this tool vs. alternatives. The description simply states what it does without mentioning use cases, exclusions, or relationships to other compute tools. The reader is left to infer that this is for retrieving shape options.

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 of behavioral disclosure. It does not explicitly state that this is a read-only operation, nor does it mention authentication requirements, potential side effects, or response characteristics. The region scoping is noted but other behavioral traits are absent.

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, concise sentence that front-loads the core purpose. There is no wasted wording, making it efficiently scannable for an agent.

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 being a low-complexity tool, the absence of an output schema and annotations means the description should clarify return values or usage context. It does not, leaving the agent to infer the response format and when to invoke this over other list tools. The description is minimal and could be more complete.

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 input schema covers 100% of parameters, with compartment_id described as 'Compartment OCID (defaults to tenancy)'. The description adds no parameter-specific information, but the schema is sufficient, so a baseline 3 is appropriate.

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 'List availability domains in the region' uses a specific verb and resource, clearly distinguishing it from sibling tools like oci_iam_list_users or oci_compute_list_instances. It precisely states what the tool does with no ambiguity.

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, nor does it mention any prerequisites or exclusions. It simply restates the function without contextualizing its purpose among the IAM or compute siblings.

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

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

No annotations are provided, so the description carries the full burden. It conveys a read-only list operation and adds the 'tenancy hierarchy' scope, but it does not disclose pagination, return format, or whether the listing is recursive through the hierarchy.

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, concise sentence that is front-loaded with the action and resource. Every word serves a purpose, with no redundancy or filler.

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

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

For a simple list tool with fully described parameters, the description is adequate. It could clarify whether it lists immediate children or all descendants, but the schema's compartment_id default and the 'tenancy hierarchy' phrasing give enough context for typical usage.

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 input schema fully describes both parameters (limit and compartment_id), providing 100% coverage. The description's mention of 'tenancy hierarchy' slightly reinforces the parent-child relationship but adds minimal semantic value beyond the schema.

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 lists compartments within the tenancy hierarchy, using a specific verb and resource. It distinguishes itself from sibling IAM list tools like users, groups, and policies by naming the resource type.

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 does not explicitly state when to use this tool versus alternatives, but the resource type makes it self-evident for enumeration tasks. It lacks exclusions or alternative recommendations, leaving usage largely implied.

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

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

No annotations are provided, so the description carries the full burden for behavioral disclosure. It only states the basic action without mentioning read-only nature, pagination behavior, permission requirements, or default limits beyond what's in the schema.

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

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

The description is a single concise sentence with no unnecessary words, front-loading the core purpose.

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, the description is minimally sufficient but lacks usage context and behavioral details that would be helpful given no annotations or output schema. It doesn't mention what happens when no compartment is specified or any pagination, making it incomplete for an agent making informed decisions.

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 input schema already covers both parameters (limit and compartment_id) with descriptions, so the description adds no additional information. It does not elaborate on how the parameters affect results or any special behaviors.

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 function using the verb 'List' and identifies the resource as 'IAM groups' with scope 'tenancy'. This distinguishes it from sibling tools like list_users and list_policies.

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 guidance is provided on when to use this tool versus alternatives, such as whether to use for specific compartments or how it compares to other list tools. The description offers no exclusions or prerequisites.

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 carries full burden. It only states 'List' which implies read-only, but provides no details about default compartment behavior (compartment_id defaults to tenancy), pagination via limit, or any side effects. The schema descriptions provide some of this, but the description itself adds minimal 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, concise sentence that front-loads the verb and resource. No unnecessary words are present.

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 fully described parameters, the description is adequate but misses the nuance that compartment_id is optional and defaults to tenancy. Given no annotations or output schema, the description could be more complete but is not severely lacking.

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 100% coverage with descriptions for both parameters (limit, compartment_id). The description does not add additional parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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 (list), the resource (IAM policies), and the scope (in a compartment). This distinguishes it from sibling tools like oci_iam_list_users and oci_iam_list_groups.

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 guidance is provided on when to use this tool versus alternatives. While the name implies usage, there is no explicit context or exclusions mentioned in the description.

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 for behavioral disclosure. It omits any mention of pagination, default limit behavior, permission requirements, or whether compartment_id defaults to tenancy, which is only revealed in the schema.

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

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

The description is a single, front-loaded sentence with no unnecessary words. It is appropriately concise for a simple list operation.

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 complete schema coverage, the description is mostly sufficient. However, it lacks explicit behavioral details like pagination and default scoping, which would improve completeness, though the schema partially covers these.

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 100% coverage for both parameters (limit and compartment_id), so the description does not need to add parameter details. It adds no additional semantic meaning beyond the schema descriptions, matching the baseline of 3.

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

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

The description 'List IAM users in the tenancy' uses a specific verb (List), resource (IAM users), and scope (in the tenancy), clearly distinguishing it from sibling tools like list_groups or list_policies.

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 guidance is provided on when to use this tool versus alternatives such as oci_iam_list_groups or oci_iam_list_compartments. The description simply states what it does without any context or exclusions.

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

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

No annotations are provided, so the description carries the full burden. It does not disclose any behavioral traits such as side effects (creating a resource), required permissions, reversibility, or return values. The description essentially restates the tool name without adding meaningful 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 sentence with no unnecessary words. It is front-loaded and to the point, conveying the core purpose efficiently.

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

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

With no output schema and no annotations, the description should explain what the tool returns, how it behaves, and what the parameters mean. It only states the action, omitting crucial context like the default compartment behavior, the impact of different storage tiers and public access settings, and any expected output. This is insufficient for a create operation with four parameters.

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 50% – bucket_name and compartment_id have descriptions, but storage_tier and public_access only have enums. The tool description adds no parameter information, failing to explain the meaning of storage tiers or public access options, and thus does not compensate for the missing parameter descriptions.

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 specific verb 'Create' and the resource 'Object Storage bucket', distinguishing it from sibling tools like oci_os_list_buckets, oci_os_delete_bucket, and oci_os_get_namespace. It is unambiguous and specific.

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 usage is implied by the verb 'Create' – one would use this tool when they need to create a bucket. However, there is no explicit guidance on when to use it vs alternatives, prerequisites (e.g., namespace, permissions), or exclusions. The description only states what the tool does.

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 of behavioral disclosure. It mentions only that the bucket must be empty, but does not disclose that deletion is permanent, what permissions are needed, or what happens if the bucket is non-empty. This is a significant gap for a destructive operation.

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 six-word sentence that is front-loaded and free of any unnecessary words. Every word contributes to clarity, making it highly concise and well-structured.

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

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

For a destructive tool with no annotations and no output schema, the description covers the core purpose and the critical empty-bucket precondition. However, it omits important context such as the permanence of deletion and error behavior on non-empty buckets, leaving some gaps but still adequate for a simple 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?

The input schema fully describes both parameters: bucket_name (required) and compartment_id (optional, defaulting to tenancy). The tool description adds no additional meaning to these parameters, so the schema provides the semantics, meeting the baseline for 100% schema 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 deletes an empty Object Storage bucket, using a specific verb and resource, and the 'empty' qualifier adds important scope that distinguishes it from simply deleting any bucket. This makes the purpose unambiguous compared to sibling tools like create or list.

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 the tool is used for deleting empty buckets but does not explicitly specify when to use it over alternatives, nor does it mention prerequisites beyond the bucket being empty. The use case is evident from the verb, but guidance is minimal and not explicitly stated.

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

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

No annotations are provided, so the description carries the full transparency burden. 'Get' signals a read-only operation and 'for the tenancy' clarifies scope, but the description does not disclose return format, error behavior, or any permissions/rate limits. This is acceptable for a simple getter but lacks 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, front-loaded sentence with no redundant or filler content. It states the action, resource, and scope efficiently.

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 fully documented, no output schema, and a clear resource scope. The description sufficiently conveys what the tool returns (the namespace) and its operation. A slight gap is the lack of explicit return-type info, but this is not critical for such a straightforward getter.

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?

Input schema coverage is 100%, with compartment_id already described as 'defaults to tenancy'. The description adds no parameter-level meaning beyond restating the tenancy context, so the baseline of 3 applies.

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 uses the specific verb 'Get' with the resource 'Object Storage namespace' and scope 'for the tenancy'. This clearly distinguishes the tool from sibling tools like oci_os_list_buckets or oci_os_create_bucket, making its unique purpose immediately obvious.

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 the tool is used when the tenant's Object Storage namespace is needed, but it provides no explicit guidance on when to use it versus alternatives, nor any exclusions or prerequisites. The usage context is only implied by the tool's name and resource scope.

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 disclose behavioral details, but it only adds a Free Tier storage note. The claim 'List all' conflicts with the schema's limit parameter (default 100), so the tool may not return all buckets if more exist. No pagination or read-only assurance is provided.

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 sentence with a parenthetical about Free Tier limits. It is efficient and front-loaded with the action and scope, though the Free Tier note is tangential to the tool's operation.

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 core purpose and compartment scope, but omits behavior around the limit parameter (e.g., pagination) and return format. With no output schema, additional context about what the list contains would improve completeness. The Free Tier note is helpful context but not essential.

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?

Both parameters already have clear descriptions in the schema (limit and compartment_id with default to tenancy), so the description adds little beyond what the schema provides. The phrase 'in a compartment' aligns with compartment_id but doesn't enrich the meaning.

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

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

The description uses a specific verb ('List') and resource ('Object Storage buckets') with a clear scope ('in a compartment'), distinguishing it from sibling tools like oci_os_list_objects and oci_os_delete_bucket.

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 by stating it lists buckets in a compartment, but it does not explicitly mention when to use this tool over alternatives such as oci_os_list_objects, nor does it provide exclusions. This leaves the agent to infer appropriate usage from the resource type.

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 full burden of behavioral disclosure, but it only states the basic operation. It omits any mention of pagination, default limits (e.g., limit defaults to 100), compartment defaulting, or that this is a read-only operation. This lacks transparency for an agent relying solely on the description.

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

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

A single sentence of 11 words, front-loaded with the action and resource, with no redundant content. Every word earns its place, making it highly efficient for an agent to parse.

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

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

The tool is a simple list operation with well-documented parameters, but the description omits important contextual details such as return format, pagination behavior, or any constraints. Without an output schema or annotations, the agent lacks information about what the response contains or how the list is delivered.

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 input schema already provides 100% coverage with descriptions for all four parameters, including defaults. The description adds only a hint about the prefix filter matching the schema, but does not introduce new meaning beyond what the schema already documents.

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 'List objects in a bucket with optional prefix filter' uses a specific verb ('List') and resource ('objects in a bucket'), clearly distinguishing it from sibling tools like list_buckets or compute list operations. The optional prefix filter adds useful scope without ambiguity.

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 listing bucket contents, but does not explicitly state when to use this tool versus alternatives such as oci_os_list_buckets. No exclusions or alternative suggestions are provided, leaving the agent to infer from the name and sibling context.

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 of behavioral disclosure, but it only says 'List subnets in a VCN'. It does not mention default pagination limits, compartment defaulting behavior, return format, or any side effects. The read-only nature is implied by 'List', but no other operational details are disclosed.

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, concise sentence with no filler or redundant content. It efficiently communicates the essential purpose without unnecessary detail, making it appropriately sized.

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 lacks an output schema and annotations, so the description must provide sufficient context. However, it does not explain what is returned (e.g., subnet OCIDs, names, details) or how the limit parameter affects results. This is inadequate for an agent to fully understand the tool's 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?

The input schema provides descriptions for all three parameters (vcn_id, compartment_id, limit), covering 100% of parameters. The tool description adds no additional meaning beyond what the schema already offers, so the baseline score of 3 is appropriate.

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 operation ('List'), the resource ('subnets'), and the scope ('in a VCN'). It distinguishes from sibling tools like oci_vcn_list, which lists VCNs, by specifying the subnet focus.

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, nor any prerequisites such as having a valid VCN OCID. It simply states the function without contextual usage instructions.

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 carries the full burden. It only states the action 'Create' without disclosing side effects, required permissions, idempotency, or what is returned. This is sparse and fails to provide behavioral context beyond the obvious action.

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 sentence with no wasted words. It efficiently conveys the core action, earning a high score for conciseness and structure.

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 the lack of annotations and output schema, the description is too sparse. It doesn't mention how creation affects the tenancy, how to verify the result via oci_vcn_list, or any constraints beyond the schema. The schema covers parameters but not the broader operational context.

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 100% with informative parameter descriptions (e.g., 'CIDR blocks (e.g., ['10.0.0.0/16'])'). Baseline is 3, and the tool description adds no extra parameter meaning, so it remains at baseline.

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?

Description uses specific verb 'Create' and resource 'Virtual Cloud Network', clearly distinguishing it from sibling 'oci_vcn_list' which lists VCNs. The purpose is unambiguous.

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

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

No guidance on when to use this tool vs alternatives. Does not mention prerequisites, such as needing a compartment, nor suggest using oci_vcn_list to verify creation. No exclusions or alternative tools referenced.

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 carries the full burden. 'List' implies a read-only operation with no side effects, and 'in a compartment' adds scoping context. However, it does not disclose additional behavioral traits like pagination, default limit, or authentication requirements.

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

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

The description is a single, front-loaded sentence that directly states the action and scope. Every word earns its place, with no filler or repetition.

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 with two optional parameters, both documented in the schema. The description adequately states the purpose and scope for an agent to select and invoke the tool. However, without annotations or an output schema, a bit more detail about return behavior or defaults could be added, though the schema covers the parameter defaults.

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 100%, so the schema already documents both parameters thoroughly. The description does not add extra parameter meaning beyond what the schema provides, earning the baseline score of 3.

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

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

The description uses a specific verb ('List') with a clear resource ('Virtual Cloud Networks') and scope ('in a compartment'). It distinguishes from siblings like oci_vcn_create (create) and oci_subnet_list (subnets).

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

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

Usage context is implied by the resource name and scope, but there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions. It is clear this lists VCNs, but not explicitly contrasted with oci_subnet_list or other list tools.

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