arhiiv

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description adds value by specifying the included data (biography, education, materials, linked-data, knowledge-graph relations, press mentions, and links.html for citation) without contradicting 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 two sentences, front-loaded with the core purpose, and every phrase adds value. No extraneous information.

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

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

Given the lack of output schema, the description effectively lists all returned data types, but omits error conditions, authentication needs, or rate limits. Annotations partially compensate for behavioral traits.

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% with one parameter 'slug' described as 'Artist slug, e.g. from search_artists links.' The description merely repeats the slug usage, adding no new semantic information 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 verb 'Get' and the resource 'one artist by slug', and lists the specific content included (biography, education, materials, etc.), which distinguishes it from sibling tools like get_exhibition or get_work.

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 after search_artists (slug from search_artists links) but does not explicitly state when to use this tool versus alternatives, nor does it provide when-not scenarios.

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=true and openWorldHint=true, covering safety and schema openness. The description adds value by specifying exactly which data fields are returned, helping the agent understand what to expect beyond 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 description is a single sentence that front-loads the core function ('Get one exhibition by slug') and then lists contents in a comma-separated list. No unnecessary words; every part contributes meaning.

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 tool with one parameter and no output schema, the description covers the main input method and output fields. It could mention that the result is a single object or that the slug must be unique, but overall it is adequate.

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 one parameter 'slug' of type string with no description (0% coverage). The description explicitly states that the tool retrieves 'by slug', clarifying the parameter's purpose and how it identifies the exhibition.

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 retrieves a single exhibition by slug and lists the specific fields returned (description, curator, organizers, etc.). It distinguishes itself from sibling tools like 'get_artist' or 'search_exhibitions' by focusing on a specific resource and identifier.

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 context implies usage when you have a slug and need exhibition details, contrasting with search tools. However, it lacks explicit when-not-to-use guidance or mention of alternatives like 'search_exhibitions' for cases without a slug.

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 provide readOnlyHint and openWorldHint. The description adds value by specifying the exact returned content (description, linked-data, exhibition count, graph relations), going beyond the annotations. No contradictions, but could further disclose potential variability or auth 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?

Single sentence that is efficient and front-loaded with the primary action and resource. No unnecessary words; every part contributes to understanding.

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 tool with one parameter and no output schema, the description adequately covers purpose and return fields. However, it could be more complete by explaining the nature of 'graph relations' or when this tool is preferred over get_relations. Slight gap in full 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 has one parameter 'slug' with 0% description coverage. The description only mentions 'by slug' without clarifying what constitutes a slug, its format, or how to obtain it. Minimal additional meaning 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?

Clearly states the verb 'Get', the resource 'organization', and specifies filtering by slug with examples of organizations (school, gallery, museum, association). It also lists returned fields (description, linked-data, exhibition count, graph relations), distinguishing it from siblings like get_artist or get_exhibition.

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 (e.g., get_relations or search tools). Does not mention prerequisites or context. The annotations indicate read-only and open-world nature, but the description itself lacks explicit usage direction.

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=true and openWorldHint=true. The description adds context about output format (every edge has source citation and target URL) and lists example relation types, going beyond annotations to clarify behavior.

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

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

The description is two sentences, front-loaded with the main action and examples. The first sentence is slightly dense but efficient, the second clarifies entity types and output features. No redundant 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?

For a 3-parameter tool with no output schema, the description explains entity_type and relation_type well but omits explanation of 'slug' and does not specify pagination, error behavior, or limits. The output format is partially described (citation and URL), but completeness is adequate for an experienced agent.

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 has 33% description coverage (only relation_type described). The tool description enumerates valid values for entity_type and gives examples for relation_type, adding essential meaning beyond the schema. Slug remains implicit but is assumed from context.

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 verb 'Walk' to indicate traversing the knowledge graph, specifies the resource (relations around an entity), and lists specific relation types (STUDIED_UNDER, HELD_BY) and entity types (artist, work, exhibition, organization). This distinguishes it from sibling tools like get_artist or search_artists which focus on single entities or searches.

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 exploring connections ('walk the knowledge graph') but does not explicitly state when to use this tool over alternatives or provide exclusions. Sibling tools are listed but no contrast is drawn, leaving the agent to infer 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?

Annotations provide readOnlyHint and openWorldHint. Description adds specific data returned (counts, year coverage, timestamp) without contradicting annotations. No destructive behavior indicated.

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?

Single sentence, well-structured, front-loaded with key information. 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 tool with zero parameters and no output schema, the description fully covers what the tool returns and its scope. No gaps.

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

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

No parameters required. Baseline 4 is appropriate since the description need not add parameter details.

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 explicitly states the tool returns archive-wide published counts for multiple categories (artists, works, etc.), year coverage, and timestamp. It clearly distinguishes from siblings which focus on individual entities or search.

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 is implied: the tool provides aggregate stats, not specific entity data. No explicit guidance on when to use or when not to use alternatives, but context makes it clear.

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 provide readOnlyHint and openWorldHint. The description adds useful behavioral details: events are merged and year-sorted, and scope is between two years. This goes beyond annotations and informs the agent effectively.

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 with no wasted words. The purpose is front-loaded, and every sentence adds value. Excellent 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?

The tool has no output schema, so the description should indicate what the response contains. It lists event types but not fields. For a simple read-only timeline tool, this is adequate but not fully complete for an AI agent.

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

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

Schema coverage is 0%, so description must compensate for parameter meaning. It mentions 'between two years' which loosely describes the parameters, but provides no format, constraints, or default values. This underspecifies the parameters.

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

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

Description clearly states the tool retrieves merged, year-sorted events for a chronological overview of Estonian jewellery art. It uses a specific verb-resource combination ('get timeline') and distinguishes from siblings by emphasizing aggregation.

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 phrase 'Great for a chronological overview' implies appropriate usage context, but no explicit when-not-to-use or alternatives are mentioned. Given sibling tools like get_exhibition and get_artist, the usage guidance is present but could be more explicit.

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 indicate read-only and open-world. Description adds value by enumerating the returned fields (dimensions, images, etc.), providing context beyond 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?

Single sentence, front-loaded with purpose, no 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 one required parameter and no output schema, the description covers purpose, parameter, and return content fully for a simple retrieval tool.

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

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

Schema has one parameter 'slug' with no description (0% coverage). Description says 'by slug', clarifying it's an identifier, but lacks format or 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 clearly states 'Get one work by slug' and lists specific fields returned, distinguishing it from sibling tools that search or retrieve other entities.

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?

Description implies usage when you have a specific slug, but no explicit when-to-use vs alternatives like search_works or when not to use.

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=true and openWorldHint=true. The description adds valuable behavioral context: the tool returns paginated results with specific fields (work/exhibition counts, page URLs). It does not contradict annotations and provides additional practical details.

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

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

The description is two sentences long, front-loads the purpose, and includes essential details (parameters, return type, domain). No extraneous information, 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?

Given the tool has 6 parameters and no output schema, the description explains the return type ('artist cards with work/exhibition counts and canonical page URLs') which is helpful. It could be improved by mentioning pagination metadata (e.g., total count or page size), but overall it provides sufficient context for an agent to understand the tool's output.

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% (3 of 6 parameters documented). The description adds the semantic that grad_year_from and grad_year_to form a range, which helps clarify their joint usage. However, it does not cover the missing parameter descriptions for page, grad_year_from, or grad_year_to fully.

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 identifies the tool's action ('Search the artist registry'), the specific resource ('artists'), and the parameters (name, school, graduation-year range). It also specifies the domain ('Estonian jewellery/metalwork artists'), which distinguishes it from other search tools among 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 the tool (to search for artists) but does not explicitly state when not to use it or provide alternatives. For example, it could mention that if you already have an artist ID, use get_artist 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?

Annotations already indicate readOnlyHint=true (no mutation) and openWorldHint=true (results may change). The description adds the behavioral trait that results are 'paginated', which is not covered by annotations. This provides additional useful context beyond structured fields.

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 15 words, front-loaded with the purpose. Every word is meaningful with no redundancy. It is optimally concise for an AI 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?

Given the tool has 4 parameters, no output schema, and annotations present, the description covers search criteria and output fields well. It mentions pagination but does not explain page parameter usage or default page size. Overall, it provides sufficient context for basic use.

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 has 4 parameters with 0% description coverage. The description mentions three of them (query maps to title, year, and organization_slug) but omits the 'page' parameter. It does not specify format details or constraints beyond the schema, leaving the page parameter undefined for agents.

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 verb 'Search', the resource 'exhibition database', and the search criteria ('by title, year, or organizer'). It also describes the output ('paginated exhibition cards with title, dates, venue, city, canonical URL'), which differentiates it from sibling tools like search_artists and get_exhibition.

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 searching exhibitions by criteria, but it does not explicitly state when to use this tool over alternatives (e.g., get_exhibition for a single exhibition) or when not to use it. No exclusions or comparisons to siblings 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, establishing safety and non-deterministic results. The description adds behavioral context by listing the returned data fields (master, town, active years, source). No contradictions with 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?

Two sentences effectively communicate the tool's purpose and output. No redundant or unnecessary information.

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

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

The description explains what is returned and for whom. However, it does not mention pagination or result limits, and the openWorldHint annotation is not explained. Still, the description covers the main aspects adequately for a search 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 description reiterates the three search parameters (lettering, town, century) that are already described in the schema. The page parameter is not mentioned in the description, and the schema has no description for it. With 75% schema coverage, the description adds minimal additional 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 action (search), resource (historical Estonian goldsmiths' maker's marks), and search criteria (lettering, town, century). It also specifies the return fields and audience, making it distinct from sibling tools that search different entities.

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 identifies the tool's purpose and audience, but does not explicitly state when to use this tool versus alternatives. However, the sibling tools are for different entities, so the usage context is implied. No when-not-to-use guidance is 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?

Annotations already indicate readOnlyHint=true and openWorldHint=true, so the description carries less burden. It adds context about being 'backed by the archive timeline' and the filtering options, but does not disclose additional behaviors like pagination or result limits. No contradictions with 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 concise with two sentences that front-load the core purpose and filters. Every word adds value, 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?

Given the tool has no required parameters, no output schema, and straightforward functionality, the description is fairly complete. It explains what is searched, the available filters, and the data source (archive timeline). It could mention the expected return format (list of sources), but this is not critical for a read-only search 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?

With 0% schema description coverage, the description must compensate. It explains the purpose of query (text filter against title/publication) and year range (year_from, year_to) beyond the schema's raw property names. It does not detail data types or requiredness, but provides sufficient semantic context for an AI agent to infer usage.

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 finds press and publication sources, specifying examples (Estonian newspapers via DEA, monographs) and filters (year range, text query against title/publication). It distinguishes itself from sibling tools like search_works or search_artists by focusing on press sources.

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

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

The description explains when to use the tool: to find press sources with optional year range and text query filters. It does not explicitly mention when not to use it or provide alternatives, but the context is clear enough given distinct 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?

Annotations declare readOnlyHint and openWorldHint. The description adds behavioral context: it returns paginated work cards with specific fields (artist, year, materials, thumbnail, canonical URL). This goes beyond annotations, but could mention ordering or default page size.

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: first states what it does, second describes output. No fluff, front-loaded, every sentence adds value.

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 7 parameters and no output schema, the description covers key aspects (search fields, pagination, return fields). Minor gaps: no default sort order or page size. Sufficient for typical use.

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 maps most parameters to search fields (query, material, year_from/year_to, for_sale, artist_slug), but 'query' remains ambiguous and 'page' is not addressed. Partial compensation.

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 it searches jewellery works/objects by specific fields (title, artist, material, year range, for-sale status). It distinguishes itself from sibling search tools (e.g., search_artists, search_exhibitions) by specifying 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 implies usage scenarios by listing searchable fields, but does not explicitly state when to use this tool over alternatives like search_artists or search_press. No exclusions or prerequisites are mentioned.

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