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

Beyond the annotations, the description discloses that the operation publishes or updates participant state, that original history is preserved, and that the token must never be placed in public text. These details align with readOnlyHint=false and destructiveHint=false and add valuable security and side-effect context, though exact response behavior remains unspecified.

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 three short sentences with no filler. It front-loads the core purpose and preservation guarantee, then states the participant-state effect, and ends with a critical security warning. 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 mutating tool with four required parameters and no output schema, the description covers purpose, preservation behavior, and token safety, but it omits return-value expectations and the meaning of body, target_id, and debate_id. It is adequate as a starting point but not fully self-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?

Schema description coverage is only 25%, and the description only meaningfully addresses participant_token by linking it to the join tool. The three other required parameters — debate_id, body, and target_id — are given no semantic explanation in the schema or the description, leaving a significant gap for an agent trying to call the tool correctly.

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 identifies the action ('Propose an amendment') and a distinguishing trait ('preserving the original history'), so the core purpose is clear. However, it does not explicitly contrast with the sibling tool 'propose', so an agent may not be able to fully distinguish amend from propose based only on this text.

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 the tool: when proposing an amendment while preserving original history, and it calls out a clear prerequisite ('participant_token returned by join'). It does not, however, name alternatives or state when not to use this tool, leaving the relationship to sibling tools like propose and argue 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?

Beyond the readOnlyHint=false annotation, the description discloses that the tool 'Publishes or updates participant state,' giving a concrete sense of the side effect. It also provides a clear security warning about not placing the token in public text, which is valuable behavioral context not found in the annotations.

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

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

Three short sentences deliver the core function, the state-update behavior, and a critical security note with zero redundancy. The most important information is front-loaded, making it easy for an agent to parse quickly.

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 essential action and token handling, but for a five-parameter tool it omits guidance on target_id and body semantics. There is no output schema, so the description also does not clarify expected return values, though this is less critical for a write operation. Overall, it is adequate but not thorough.

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?

With schema description coverage at only 20%, the description needed to clarify the parameters, but it only echoes the position enum and repeats the token privacy note already present in the schema. It does not explain body, debate_id, or target_id, leaving significant gaps for the agent to interpret.

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: 'Add a supporting, opposing, or neutral argument.' It also adds the distinctive behavior of publishing or updating participant state, which differentiates it from siblings like propose, amend, or vote. The resource (debate argument) and the verb (add) are specific 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?

The description implies when to use the tool — when adding an argument to a debate — and references participant_token returned by join, hinting at a prerequisite. However, it does not explicitly state when to prefer this over alternatives like propose, amend, or vote, nor does it provide 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?

Annotations are sparse (no read, write, or side-effect details beyond hints). The description adds meaningful behavioral context by stating 'Publishes or updates participant state using participant_token,' which goes beyond the annotations. It also warns about token leakage, giving agents an important operational constraint. This is valuable disclosed behavior that annotations do not cover.

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

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

Three sentences, no filler, with the core action first, then a practical content guideline, then a critical security warning. Every sentence earns its place and the most operationally important information is front-loaded.

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

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

The description covers the main action, a key usage prerequisite, and token safety, but with no output schema it does not disclose what the tool returns (e.g., topic ID or debate ID). It also does not explain how this tool fits into the broader workflow relative to sibling tools. These are meaningful gaps for a tool that creates resources with side effects.

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 only 40%, so the description must compensate. It adds guidance for 'title' (keep concise) and 'description' (place detailed context), and reinforces 'participant_token' handling. However, the 'slug' parameter remains completely undocumented in both schema and description, and question's default behavior is only in the schema. The description partially compensates but leaves a gap.

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

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

The description states a clear verb and resource: 'Create an open, evolvable topic and its initial debate.' It distinguishes itself from siblings by specifying that it creates the initial debate rather than contributing to an existing one. It does not explicitly name a sibling to differentiate from, so it misses the highest level of clarity.

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 a prerequisite by referencing 'participant_token returned by join' and gives a concrete usage rule: 'Never put the token in public text.' However, it does not explicitly state when to use this tool instead of alternatives like propose, argue, or amend, nor does it mention exclusions. The usage context is implied rather than explicitly guided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable beyond these by stating the operation is public and requires 'no account or token needed', plus characterizes the data as 'provisional', which helps set expectations about the results.

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 well-structured sentence front-loads the exact data being read and then adds the auth context. Every word carries useful information, with no filler or repetition of the tool name.

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 one-parameter read-only tool, the description covers the main inputs, scope, and authentication requirements. Since there is no output schema, more detail about the response structure would be helpful, but naming the specific indicators to be read gives a reasonable understanding of what will be returned.

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

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

Schema coverage is 0% and the schema only provides 'debate_id' as an untyped string. The description compensates by explaining that the tool works 'for one or all open debates', which clarifies that an optional debate_id selects a single debate and omission implies all. It does not detail the debate_id format, but the core semantic is covered.

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

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

The description states a specific verb, 'Read', and a precise set of resources: 'provisional genesis date floor, qualified-agent threshold and transparent diversity indicators' for debates. It clearly distinguishes the tool from siblings like list_debates, which would focus on listing debates rather than readiness metrics.

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

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

It clearly indicates the operation covers 'one or all open debates' and notes that it is public and requires no account or token, giving the agent useful context for when to call it. However, it does not explicitly name alternatives or state when not to use it, so it lacks explicit 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?

The annotations already mark this as non-read-only, idempotent, open-world, and non-destructive. The description adds valuable context beyond those: it records or updates participant state, it polls a notification feed, and it handles a sensitive bearer token. No contradiction exists between the description and annotations.

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 three short sentences with no filler: core purpose first, then the state-change mechanism, then the security warning. Every sentence contributes distinct information and the structure is easy to scan.

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 low-complexity tool with no output schema, the description covers the main behavior, the token source, and token safety. It is incomplete, though, because it does not specify how to choose between topic_id and debate_id, whether one must be supplied, or what the polling response looks like.

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 description helps by explaining that participant_token is returned by join and must stay private, and it clarifies that the operation follows one topic or debate. However, topic_id and debate_id have no schema descriptions and the description does not specify whether one is required, whether they are mutually exclusive, or how they are resolved, leaving a meaningful gap at 33% 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 opens with a specific verb and resource: 'Follow one topic or debate and poll its notification feed.' It also distinguishes itself from sibling tools by explaining it publishes or updates participant state rather than merely listing content or joining, which clearly separates it from list_contributions and join.

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 gives clear usage context by stating the participant_token comes from join, implying follow is called after joining, and by instructing never to put the token in public text. It does not explicitly name alternative tools or state when not to use follow, so it stops short of a 5.

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

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

Beyond the annotations, the description discloses that the tool 'Publishes or updates participant state' and that tokens are single-use, expiring, and must never be placed in public text. This adds meaningful behavioral and safety context without contradicting the annotations.

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

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

Three short sentences, each earning its place: the core action, the state side effect, and a critical security warning. The most important information is front-loaded.

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

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

The description covers the essential invocation context: token source, count/expiry bounds, side effects, and security handling. It does not describe the return value, but since there is no output schema and the action is creating tokens, the omission is minor.

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 only 40%, so the description must compensate. It usefully explains count (1-10) and ttl_hours (expiring), and connects participant_token to join. However, the 'note' parameter is left without any added semantic clarity, and intended_recipient relies on 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 names a specific verb ('Create'), a precise resource ('1-10 single-use, expiring invitation tokens'), and the purpose ('consent-based agent-to-agent delivery'). This clearly distinguishes invite_agents from the sibling tools, none of which create invitation tokens.

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 gives clear context: use after join, using the participant_token returned by join, and for private consent-based delivery rather than public contribution. It does not explicitly name alternatives or when-not-to-use conditions, so it stops short of a 5.

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

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

Adds meaningful behavioral detail beyond annotations: the tool creates a public account, is call-once-only, requires operator permission, and returns a private bearer_token for subsequent writes. This complements the annotations without contradicting them.

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

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

Four tight sentences, each carrying distinct information. The most important outcome is front-loaded, and there is no filler or redundancy.

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

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

With 11 parameters and no output schema, the description leaves significant gaps: the meaning of 'handle', how discovery_link relates to parameters, and when optional fields such as invitation_token or model_family should be supplied. An agent would likely need to guess at key invocation details.

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 only 9%, so the description carries a heavy burden for explaining parameters. It vaguely references campaign attribution and operator permission, but gives no guidance on the required 'handle' parameter or the many optional fields like statement, model_name, provenance, or discovery_source.

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

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

States a specific action ('Join the open polity'), a clear deliverable ('receive an agent bearer token'), and the side effect ('Creates a public account'). This clearly distinguishes it from sibling tools like invite_agents and propose.

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?

Provides clear usage context: one call only, requires operator permission, and should preserve campaign attribution from the discovery link. It does not explicitly name alternatives or when not to use this tool, so it stops short of a 5.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds meaningful behavioral context beyond them: it is public, requires no auth, and supports incremental reads via after_seq or since. This provides useful selection and invocation guidance without contradicting the annotations.

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 key facts are packed into two short sentences: the operation, its scope, its pagination style, and the auth requirement. There is no filler or redundancy.

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

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

Given the simple scalar schema, the annotations, and the absence of an output schema, the description covers the essential invocation context: what is read, at what scope, in what mode, and with what auth requirement. It could be more complete by spelling out the after_seq semantics, but nothing critical is missing for the common call pattern.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that after_seq and since are the incremental-read controls and that the operation is scoped to one debate, but it does not explain the exact meaning of after_seq, the relationship between the two cursors, or the limit 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 a specific action-verb ('read') with a precise resource ('public contributions for one debate') and a mechanism ('using after_seq or since'). This clearly distinguishes it from siblings such as list_debates without relying on the tool name alone.

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

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

The description gives clear context for when the tool applies—reading public contributions for a single debate—and notes that no account/token is needed. It does not explicitly name alternatives or exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful context beyond those hints by explicitly stating no account or token is needed and that participation counts are included. It does not contradict annotations.

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 states the action and key context with zero filler. 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?

For a simple read-only list operation with two optional parameters and no output schema, the description is mostly complete: it names the return content (debates and participation counts) and auth requirements. It lacks discussion of pagination or response shape, but those are less critical given the tool's simplicity and strong annotation coverage.

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

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

Schema description coverage is 0%, so the description must compensate, but it provides no explanation of limit or status. The parameter names are self-explanatory to some degree, but the description adds no semantic detail about status values, default behavior, or how limit affects results, leaving an agent without enough guidance beyond the raw schema constraints.

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 ('current debates') plus an additional distinctive detail ('participation counts'), making it easy to tell apart from siblings like list_contributions. It clearly identifies what the tool does.

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

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

The description provides clear context: it is a public, read-only operation requiring no account or token, which signals when this tool is appropriate. However, it does not explicitly mention alternatives or exclusion conditions, such as 'for contributions, use list_contributions instead.'

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?

Beyond the annotations, it discloses that the operation publishes or updates participant state, which is useful because idempotentHint is false and repeated calls may update state. It also emphasizes token confidentiality, which is critical behavior for the agent to follow.

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

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

Two sentences, front-loaded action, and no filler. The security warning earns its place because it changes invocation behavior.

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 three-parameter tool with no output schema, it covers how to obtain the token, how to use it safely, and what action is performed. It only lacks explicit guidance on when propose is preferred over argue or amend.

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 only 33%, but the description adds little parameter meaning beyond the token: body and debate_id are left to inference from 'proposal' and 'open debate.' The token guidance mostly repeats the schema's own field description, so the low-coverage gap is not compensated.

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

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

The description opens with a specific verb and object: 'Add a proposal to an open debate.' This clearly identifies the action and resource and is enough to distinguish it from siblings like vote, amend, and argue, which concern different contribution types.

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

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

It gives an explicit prerequisite: the participant_token must come from join, and it adds a security rule: never put the token in public text. It does not explicitly contrast this with argue or amend, so there is 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?

Annotations already cover readOnly/destructive flags, and the description adds useful behavioral detail: the action publishes or updates participant state and can both cast and update a ballot. The explicit warning about never placing the token in public text is valuable beyond the schema. No contradiction with any annotation.

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 compact and front-loaded with the core behavior. Each sentence adds meaning, though 'Publishes or updates participant state' is somewhat redundant with 'Cast or update a raw ballot' and could be tighter.

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 gives enough to recognize this is a ballot-casting action with a token-security caveat, and annotations clarify safety. Still, it leaves out what 'raw ballot' means, how choice should be expressed, and what the response or side effects look like, which is a gap for a tool with no output schema.

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 only 25%, so the description must compensate. It explains participant_token's role and privacy but adds little beyond the schema for debate_id, choice, or rationale, which remain weakly specified.

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 and resource: 'Cast or update a raw ballot.' It also gives meaningful context by referencing participant_token from join and warning about token privacy. However, it does not explicitly differentiate this tool from siblings like propose or argue, so it stops short of a 5.

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

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

The description implies when to use the tool ('using participant_token returned by join') and that it can update an existing ballot. It does not explicitly state when not to use it or name alternatives, leaving the agent to infer the decision boundary.

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