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 effectively communicates key traits: it's a read-only operation (explicitly marked '[READ-ONLY]'), requires specific permissions ('tables:read' scope), and corresponds to a specific API endpoint. It doesn't mention rate limits or error conditions, but covers the essential safety and access profile.

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 extremely concise (just two sentences) and front-loaded with the core purpose. Every element earns its place: the action, resource, API correspondence, permission requirement, and read-only designation all serve distinct purposes without redundancy or fluff.

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

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

For a simple read operation with one parameter and no output schema, the description is reasonably complete. It covers purpose, permissions, and behavioral safety. However, without an output schema, it doesn't describe what the count returns (e.g., integer format, error responses), leaving some ambiguity about the result structure.

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% description coverage, with the single parameter 'tableId' clearly documented in the schema. The description doesn't add any additional parameter meaning beyond what the schema already provides (e.g., no examples of table IDs or format requirements), so it meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Counts records') and resource ('in a Tulip Table'), distinguishing it from sibling tools like listTableRecords (which lists records) or getTable (which retrieves table metadata). The verb+resource combination is precise 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 provides clear context by mentioning the required scope ('tables:read'), which helps determine when this tool can be used. However, it doesn't explicitly differentiate when to use this versus alternatives like listTableRecords (which might provide more detailed record information) or getTableAggregation (which might perform other calculations).

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 and does well by disclosing key behavioral traits: it specifies the HTTP method (GET), API endpoint, and required authentication scope ('stations:read'). It also marks the operation as '[READ-ONLY]', clarifying it's non-destructive. However, it doesn't cover aspects like rate limits, error handling, or response format, which could be useful for an agent.

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 front-loaded with the core purpose, followed by technical details (API endpoint, scope, read-only note) in a single, efficient sentence. There is no wasted text, and every part adds value, making it highly concise and well-structured for quick 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?

Given the tool's simplicity (1 parameter, no output schema, no annotations), the description is reasonably complete for a basic read operation. It covers purpose, authentication, and safety, but lacks details on output format or error cases, which could be helpful for an agent invoking the tool without an output schema. It's adequate but has minor gaps in 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?

The input schema has 100% description coverage, with the parameter 'interfaceId' clearly documented. The description does not add any semantic details beyond what the schema provides, such as format examples or constraints. Given the high schema coverage, a baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't need to heavily.

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 ('Gets details') and resource ('specific interface'), making the purpose understandable. However, it does not explicitly differentiate this tool from sibling tools like 'listInterfaces' or 'getStation', which might also retrieve interface-related information, leaving some ambiguity about when to use this specific retrieval method.

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 specifying it retrieves details for a 'specific interface' and mentions a required scope, suggesting it's for detailed lookups when an interface ID is known. However, it lacks explicit guidance on when to use this versus alternatives like 'listInterfaces' for broader queries or other get tools for related resources, 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates key traits: it's a read-only operation (explicitly stated), requires specific authorization ('stations:read' scope), and corresponds to a specific API endpoint. It doesn't cover rate limits or error behaviors, but provides essential operational 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 perfectly concise and front-loaded: it states the core purpose first, then adds essential operational details (API endpoint, required scope, read-only nature) in a single efficient sentence. Every element earns its place with 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 retrieval tool with one parameter and no output schema, the description provides good coverage: purpose, authorization requirements, and behavioral constraints. It could mention what details are returned or error cases, but given the tool's simplicity and lack of annotations, it's reasonably 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 has 100% description coverage, with the stationId parameter fully documented in the schema. The description doesn't add any parameter-specific information beyond what's already in the schema, so it meets the baseline of 3 where 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 clearly states the specific action ('Gets details') and resource ('about a specific station'), distinguishing it from sibling tools like listStations (which lists multiple stations) and getStationGroup (which retrieves group information). The verb+resource combination is precise 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 provides clear context by specifying the required scope ('stations:read') and marking it as read-only, which helps determine when to use it. However, it doesn't explicitly contrast with alternatives like listStations or mention when not to use this tool (e.g., for multiple stations).

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 and adds valuable behavioral context: it specifies the required scope ('stations:read'), indicates it is read-only via '[READ-ONLY]', and mentions the corresponding API endpoint. This covers key aspects like authentication needs and safety, though it lacks details on rate limits or error handling.

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 highly concise and front-loaded, with every sentence earning its place: the first states the purpose, the second provides the API endpoint, and the third covers scope and read-only status. There is no wasted text, making it 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?

Given the tool's low complexity (one parameter, no output schema, no annotations initially), the description is reasonably complete: it explains the purpose, authentication, and safety. However, without an output schema, it does not describe return values (e.g., what details are included), which is a minor gap for a 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 description coverage is 100%, so the schema fully documents the single parameter 'stationGroupId'. The description does not add any extra meaning beyond what the schema provides (e.g., format examples or constraints), resulting in a baseline score of 3 for adequate but no additional value.

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 ('Gets') and resource ('details about a specific station group'), making the purpose unambiguous. However, it does not explicitly differentiate from siblings like 'listStationGroups' (which likely lists multiple groups) or 'getStation' (which retrieves individual stations), though the specificity of 'specific station group' implies singular retrieval.

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 specifying it retrieves details for a 'specific station group', suggesting it should be used when the ID is known, as opposed to listing all groups. However, it does not explicitly state when to use alternatives like 'listStationGroups' or provide exclusions, leaving some ambiguity for the agent.

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?

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It effectively adds context by specifying the required scope ('tables:read') and explicitly marking it as read-only, which helps the agent understand permission needs and safety. However, it lacks details on rate limits, error handling, or response format, preventing a perfect score.

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 front-loaded with the core purpose, followed by essential details like the corresponding API endpoint and requirements. It uses only two sentences with zero waste, making it highly efficient and easy to parse 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's low complexity (one required parameter, no output schema), the description is reasonably complete. It covers the purpose, scope requirement, and read-only nature, which are key for a simple retrieval tool. However, without an output schema, it could benefit from hinting at the return type (e.g., table details object), slightly limiting 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?

The input schema has 100% description coverage, with the 'tableId' parameter clearly documented. The description doesn't add any extra meaning about the parameter beyond what the schema provides, such as format examples or constraints. Thus, it meets the baseline score of 3, as 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 clearly states the action ('Gets details about') and resource ('a Tulip Table'), making the purpose understandable. However, it doesn't explicitly differentiate this tool from similar siblings like 'getTableRecord' or 'listTables', which might also retrieve table-related information, so it doesn't reach the highest score.

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 includes a prerequisite ('Requires `tables:read` scope') and indicates it's read-only, which provides some context for when to use it. However, it doesn't specify when to choose this tool over alternatives like 'listTables' for listing multiple tables or 'getTableRecord' for individual records, leaving usage implied rather than 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?

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It effectively adds context by specifying the required scope ('tables:read') and labeling the operation as '[READ-ONLY]', which informs the agent about authentication needs and safety. However, it lacks details on rate limits, error handling, or response format, preventing a score of 5.

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 highly concise and front-loaded, with three key pieces of information in two sentences: the core purpose, the corresponding API endpoint, and the required scope with a read-only label. Every sentence earns its place without redundancy, making it efficient 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?

Given the tool's complexity (simple lookup with two parameters), 100% schema coverage, and no output schema, the description is reasonably complete. It covers purpose, endpoint mapping, and authentication scope. However, it lacks details on the return value format or potential errors, which could enhance completeness for an 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?

The input schema has 100% description coverage, with clear documentation for both parameters ('tableId' and 'aggregationId'). The description does not add any additional meaning beyond what the schema provides, such as format examples or constraints. Thus, it meets the baseline of 3, as the schema handles 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 clearly states the tool's purpose: 'Looks up a table aggregation for a Tulip Table by id.' It specifies the verb ('looks up'), resource ('table aggregation'), and identifier mechanism ('by id'). However, it does not explicitly differentiate from siblings like 'getTable' or 'listTableAggregations', which is why it scores 4 instead of 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 provides some usage context by mentioning the required scope ('tables:read') and labeling it as '[READ-ONLY]', which implies it's safe for retrieval operations. However, it does not explicitly state when to use this tool versus alternatives like 'listTableAggregations' or 'runTableAggregation', leaving usage guidelines implied rather than 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?

With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it specifies the required scope ('tables:read') and explicitly marks it as '[READ-ONLY]', indicating it's a safe, non-destructive operation. It also references the corresponding API endpoint, adding context. However, it doesn't cover aspects like rate limits, error handling, or response format.

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 appropriately sized and front-loaded, with every sentence earning its place: it states the purpose, maps to the API endpoint, specifies the required scope, and indicates read-only status. There is no wasted text, making it highly efficient and clear.

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 (single parameter, read-only), no annotations, and no output schema, the description is somewhat complete but has gaps. It covers the action, scope, and safety, but lacks details on return values, error cases, or how it differs from sibling tools. This makes it adequate but not fully comprehensive for an agent's needs.

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 fully documents the single parameter 'tableLinkId'. The description adds no additional meaning beyond what the schema provides (e.g., no examples or constraints), resulting in a baseline score of 3. Since there are parameters, it doesn't qualify for the baseline 4 for zero parameters.

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

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

The description clearly states the action ('fetches information') and resource ('about a table link'), distinguishing it from siblings like getTable, getTableRecord, or listTableRecords. However, it doesn't explicitly differentiate from getTableAggregation or getTableQuery, which might also fetch table-related information, leaving some 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 by specifying the required scope ('tables:read') and indicating it's read-only, which suggests it's for retrieving data without modification. However, it lacks explicit guidance on when to use this tool versus alternatives like getTable or getTableRecord, or any exclusions (e.g., not for listing multiple links).

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 effectively adds context by stating the required scope ('tables:read') and marking it as '[READ-ONLY]', which clarifies safety and permission needs. However, it doesn't mention rate limits, response format, or error handling, leaving minor gaps.

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 front-loaded with the core purpose, followed by essential details like the API endpoint and scope requirement. Every sentence adds value without redundancy, making it highly efficient and well-structured.

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

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

Given no annotations and no output schema, the description provides basic completeness by covering purpose, scope, and safety. However, it lacks details on return values, error cases, or behavioral nuances, which are important for a tool with no structured output documentation.

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% description coverage, clearly documenting both parameters. The description doesn't add any additional meaning or context beyond what the schema provides, such as format examples or constraints, so it meets the baseline but doesn't enhance understanding.

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 ('Looks up') and resource ('a table query for a Tulip Table by id'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'getTable' or 'listTableQueries', which prevents a perfect score.

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 specifying the required scope ('tables:read'), but it doesn't provide explicit guidance on when to use this tool versus alternatives like 'getTable' or 'listTableQueries'. This leaves some ambiguity for the agent in selecting among similar tools.

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 effectively communicates that this is a read-only operation ('[READ-ONLY]'), specifies the required permission scope ('tables:read'), and indicates it's a specific retrieval operation rather than a list operation. However, it doesn't mention potential error conditions, rate limits, or response format 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 extremely efficient with three concise, information-dense sentences. Each sentence adds distinct value: the core functionality, the API endpoint reference, and the permission requirement with read-only designation. There's zero wasted verbiage.

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 operation with 2 parameters and no output schema, the description provides good context: purpose, API mapping, permission requirements, and read-only nature. However, without annotations or output schema, it could benefit from mentioning what the return value contains (record data) or potential error cases.

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 description coverage is 100%, with both parameters clearly documented in the schema. The description doesn't add any additional parameter information beyond what's already in the schema, so it meets the baseline expectation but doesn't provide extra value. The mention of the API endpoint structure reinforces the parameter usage but doesn't add semantic 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?

The description clearly states the specific action ('Gets a specific record'), resource ('from a Tulip Table'), and scope ('specific record' vs. list operations). It distinguishes from sibling tools like 'listTableRecords' by specifying retrieval of a single record rather than listing multiple records.

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 by mentioning the required scope ('tables:read') and the HTTP method equivalence ('GET /tables/{tableId}/records/{recordId}'), which helps understand when to use it. However, it doesn't explicitly state when NOT to use it or name specific alternatives like 'listTableRecords' for bulk retrieval.

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 full burden and does well by disclosing the required scope ('users:read') and explicitly marking it as '[READ-ONLY]', which clarifies it's a safe read operation. It also mentions the corresponding API endpoint, adding implementation context. However, it doesn't cover potential errors, rate limits, or response format 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 efficiently structured in a single sentence with zero waste, front-loading the core purpose and including essential details like scope and read-only status. Every element adds value without redundancy.

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

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

Given the tool's simplicity (one parameter, no output schema, no annotations), the description is adequate but has gaps. It covers purpose, scope, and read-only nature, but lacks details on return values, error handling, or behavioral nuances. For a basic read tool, this is minimally viable but 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?

Schema description coverage is 100%, so the schema already fully documents the single parameter 'userId'. The description adds no additional meaning or context about the parameter beyond what's in the schema (e.g., format examples or constraints), meeting the baseline for high 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 verb ('Gets') and resource ('details about a specific user'), making the purpose unambiguous. It distinguishes from listUsers by focusing on a single user rather than listing multiple users, though it doesn't explicitly name that sibling alternative.

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 context by specifying it requires 'users:read' scope, which suggests when authentication is needed. However, it doesn't provide explicit guidance on when to use this versus listUsers or other user-related tools, nor does it mention any prerequisites or exclusions beyond the scope requirement.

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 effectively communicates key traits: the operation is read-only (explicitly marked '[READ-ONLY]'), requires specific authorization ('users:read' scope), and corresponds to a specific API endpoint (GET /api/users/v1/user-groups/{userGroupId}). This covers safety, permissions, and technical context adequately for a read 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 highly concise and front-loaded, with all essential information in one sentence: purpose, API correspondence, authorization requirement, and read-only nature. Every element earns its place without redundancy, making it efficient for an AI agent to parse and understand.

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 (single parameter, read-only operation) and 100% schema coverage, the description is reasonably complete. It covers purpose, authorization, and behavioral traits. The lack of an output schema is a minor gap, as the description doesn't detail return values, but this is acceptable for a simple retrieval tool where the response is implied by the purpose.

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 the single parameter 'userGroupId' fully documented in the schema as 'The ID of the user group to retrieve'. The description doesn't add any additional parameter semantics beyond what the schema provides, such as format examples or constraints. Baseline 3 is appropriate when the schema handles parameter documentation completely.

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 ('Gets details about') and resource ('a specific user group'), making the purpose unambiguous. It distinguishes from sibling tools like 'listUserGroups' by specifying retrieval of a single group rather than listing multiple. However, it doesn't explicitly contrast with 'getUserGroupUsers', which is a related but distinct operation.

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

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

The description implies usage context by mentioning the required scope ('users:read') and specifying retrieval of a 'specific' user group, suggesting it's for detailed lookup rather than listing. However, it doesn't explicitly state when to use this tool versus alternatives like 'listUserGroups' for bulk retrieval or 'getUserGroupUsers' for group membership details, leaving some ambiguity.

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 effectively adds context by specifying the required scope ('users:read'), marking it as '[READ-ONLY]' (indicating non-destructive behavior), and mentioning the corresponding API endpoint. However, it does not cover aspects like rate limits, pagination, or error handling.

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 appropriately sized and front-loaded, with three concise sentences that each add value: stating the purpose, specifying the API endpoint, and noting the required scope and read-only nature. There is no wasted information, making it highly efficient.

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 (single parameter, no output schema, no annotations), the description is mostly complete. It covers purpose, API correspondence, scope, and read-only behavior, but lacks details on output format (e.g., list structure) or potential errors, which would be helpful for an 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?

The input schema has 100% description coverage, with the parameter 'userGroupId' fully documented. The description does not add any additional meaning or details beyond what the schema provides, such as format examples or constraints, so it meets the baseline for high schema coverage without 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 the verb ('Gets') and resource ('users in a specific user group'), making the purpose explicit. It distinguishes this tool from siblings like 'getUser' (which retrieves a single user) and 'listUsers' (which lists all users without group filtering), providing specific differentiation.

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

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

The description includes a required scope ('users:read') and implies usage when needing users within a group, but it does not explicitly state when to use this tool versus alternatives like 'listUsers' or 'getUserGroup'. It provides clear context but lacks explicit exclusions or named alternatives.

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 effectively communicates that this is a read-only operation ('[READ-ONLY]'), specifies the required authentication scope ('Requires `users:read` scope'), and references the underlying API endpoint, adding valuable context beyond basic functionality. It does not mention rate limits or error behaviors, but covers the essential safety and access aspects well.

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 highly concise and front-loaded, with every sentence earning its place: it states the purpose, provides API correspondence, specifies required scope, and indicates read-only status in just two sentences. There is no redundant or unnecessary information, making it efficient 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?

Given the tool's low complexity (single parameter, no output schema), the description is largely complete, covering purpose, authentication, and behavioral traits. However, without an output schema, it does not describe the return values (e.g., what details are included in the role response), which is a minor gap for a read operation. The inclusion of API endpoint reference adds helpful 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?

The input schema has 100% description coverage, with the 'userRoleId' parameter fully documented in the schema. The description does not add any additional meaning or clarification about the parameter beyond what the schema provides, such as format examples or constraints. This meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Gets details') and resource ('about a specific user role'), distinguishing it from sibling tools like 'getUser' (for individual users) or 'listUserRoles' (for listing multiple roles). It provides a precise verb+resource combination that leaves no ambiguity about its 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 explicitly states when to use this tool ('Gets details about a specific user role') and mentions the required scope ('users:read'), providing clear context. However, it does not specify when NOT to use it or explicitly name alternatives like 'listUserRoles' for listing all roles, which prevents a perfect score.

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

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

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It effectively adds value by specifying the HTTP method (GET), API scope requirement ('apps:read'), and read-only nature ('[READ-ONLY]'), which informs the agent about authentication needs and safety. However, it lacks details on rate limits, pagination, or error handling.

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 highly concise and well-structured in a single sentence, with every element (purpose, API endpoint, scope requirement, read-only note) adding essential value without redundancy. It is front-loaded with the core purpose, making it efficient for the 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?

Given the tool's low complexity (0 parameters, no output schema), the description is mostly complete, covering purpose, API mapping, authentication, and safety. However, without an output schema, it does not describe the return format (e.g., structure of the list), which could help the agent interpret results, leaving a minor gap.

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 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately does not discuss parameters, maintaining focus on the tool's purpose and behavior. A baseline of 4 is applied as it compensates for the lack of parameters by not introducing unnecessary information.

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 ('Retrieves') and resource ('list of all Tulip App Groups and their containing apps'), making the purpose specific and unambiguous. It distinguishes this tool from siblings like listTables or listUsers by specifying it deals with App Groups and their apps, not other resource 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?

The description provides clear context for when to use this tool by mentioning it corresponds to GET /appGroups and requires the 'apps:read' API key scope, which helps the agent understand prerequisites. However, it does not explicitly state when not to use it or name alternatives for similar operations, such as if there are other ways to retrieve app groups.

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 effectively describes key traits: it's a read-only operation (explicitly marked '[READ-ONLY]'), requires specific permissions ('stations:read' scope), and outlines the operation's nature (paginated, filtered, sorted). It does not mention rate limits or error handling, but covers essential behavioral aspects well.

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 highly concise and front-loaded, with every sentence earning its place: it states the purpose, maps to the API endpoint, specifies the required scope, and declares read-only status. There is no wasted information 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 tool's complexity (list operation with filtering/sorting/pagination), no annotations, and no output schema, the description is mostly complete. It covers purpose, authentication, and behavioral traits, but lacks details on output format, pagination behavior, or error cases, which would enhance completeness for an 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 description coverage is 100%, so the schema already fully documents the parameters (limit, offset, sort). The description adds no additional parameter semantics beyond what the schema provides, such as examples or constraints. This meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Gets'), resource ('list of interfaces'), and scope ('paginated, filtered, and sorted'), distinguishing it from siblings like getInterface (singular) or listStations (different resource). It explicitly mentions the corresponding API endpoint for 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 provides clear context by specifying the required scope ('stations:read'), which indicates when authentication is needed. However, it does not explicitly state when to use this tool versus alternatives like getInterface (for a single interface) or other list tools for different resources, leaving some sibling differentiation implicit.

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

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

With no annotations provided, the description carries full burden and does well: it discloses the tool is read-only (via '[READ-ONLY]'), specifies required API scope ('machines:read'), and implies safe retrieval behavior. It lacks details on rate limits, pagination, or error handling, but covers key behavioral traits adequately for a read 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 front-loaded with the core purpose, followed by API correspondence and requirements, all in three concise sentences with zero waste. Each sentence adds value: retrieval scope, HTTP method mapping, and authorization details.

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 (0 parameters, no output schema, no annotations), the description is nearly complete: it covers purpose, API mapping, and authorization. It lacks output details (e.g., format or structure of the list) and potential constraints like pagination, but for a simple read tool, this is sufficient with minor gaps.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately does not discuss parameters, maintaining focus on the tool's purpose and usage. A baseline of 4 is applied as it compensates for the lack of parameters by not adding unnecessary information.

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 action ('Retrieves a list') and resources ('all Tulip machine types and their corresponding machines'), and distinguishes from siblings by specifying it's about machine types rather than stations, tables, users, etc. The mention of 'Corresponds to GET /machines' reinforces the exact operation.

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

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

The description explicitly states when to use this tool ('Requires the `machines:read` API key scope'), providing clear context for authorization. However, it does not specify when not to use it or name alternatives (e.g., vs. listStations or retrieveMachineActivityArchive), missing explicit sibling differentiation.

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 effectively adds context by specifying the required scope ('stations:read') and indicating it's a read-only operation ('[READ-ONLY]'), which covers safety and permission aspects. However, it lacks details on rate limits, pagination, or response format.

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 front-loaded with the core purpose, followed by API endpoint and scope details in a single, efficient sentence. Every element (action, resource, endpoint, scope, read-only note) adds value without redundancy, making it appropriately sized and zero waste.

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

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

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is complete enough by covering purpose, endpoint, scope, and read-only nature. However, it could improve by mentioning the return format or any limitations, but this is not critical for a simple read operation.

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% description coverage, with the parameter 'stationId' clearly documented. The description does not add any meaning beyond what the schema provides, such as examples or constraints, so it meets the baseline of 3 where 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 clearly states the specific action ('Gets app assignments') and resource ('for a station'), distinguishing it from sibling tools like listStations (which lists stations) or listStationGroupAppAssignments (which focuses on station groups). The verb 'Gets' is precise 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 explicitly states when to use this tool by specifying the required scope ('stations:read'), but it does not mention when not to use it or provide alternatives among sibling tools. For example, it doesn't differentiate from listStationGroupAppAssignments, which might be a related alternative.

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 adds useful context: the HTTP method (GET), endpoint path, required scope, and explicitly marks it as READ-ONLY. However, it doesn't describe response format, pagination, error conditions, or other behavioral traits, leaving gaps for a mutation-free 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 appropriately concise with three key pieces of information in one sentence: purpose, endpoint, and requirements. It's front-loaded with the core purpose, though the bracketed '[READ-ONLY]' could be integrated more smoothly.

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 basics (purpose, endpoint, auth) adequately. However, it lacks details on return values, error handling, or pagination, which would be helpful given the absence of annotations and 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 100%, so the schema already fully documents the single parameter. The description doesn't add any parameter-specific information beyond what's in the schema, maintaining the baseline score of 3 for high 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's purpose with a specific verb ('Gets') and resource ('app assignments for a station group'), making it easy to understand what it does. However, it doesn't explicitly differentiate from sibling tools like 'listStationAppAssignments' or 'getStationGroup', which would require 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 mentions a required scope ('stations:read'), which provides some context, but offers no guidance on when to use this tool versus alternatives like 'listStationAppAssignments' or 'getStationGroup'. It lacks explicit when/when-not instructions or named alternatives.

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 effectively indicates that the operation is read-only (via '[READ-ONLY]'), paginated, and filtered/sorted, and specifies the required scope. However, it lacks details on rate limits, error handling, or what constitutes a 'filtered' list (e.g., default filters).

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 extremely concise and front-loaded, with every sentence adding value: it states the purpose, maps to the API endpoint, specifies the required scope, and declares read-only behavior. There is no wasted text, making it efficient 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?

Given the tool's complexity (list operation with pagination, filtering, sorting) and lack of annotations and output schema, the description is reasonably complete. It covers the core behavior, scope requirement, and read-only nature. However, it could improve by mentioning output format or example usage, but the absence of an output schema is mitigated by the clear purpose.

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 fully documents the three parameters (limit, offset, sort). The description does not add any parameter-specific semantics beyond what the schema provides, such as default values or constraints. The baseline score of 3 is appropriate as the schema handles the parameter documentation adequately.

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 ('Gets'), resource ('paginated, filtered, and sorted list of station groups'), and scope ('list'), distinguishing it from siblings like getStationGroup (singular retrieval) and listStations (different resource). It specifies the exact API endpoint, making the purpose highly 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 explicitly states when to use this tool by mentioning the required scope ('stations:read'), which is crucial for authorization. However, it does not differentiate when to use this versus alternatives like listStations or getStationGroup, nor does it provide exclusions or prerequisites beyond the scope requirement.

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 full burden and does well by disclosing key behavioral traits: it's a read-only operation (explicitly marked '[READ-ONLY]'), requires specific authorization ('stations:read' scope), and corresponds to a specific API endpoint. It doesn't mention rate limits, pagination details beyond 'paginated', or error behaviors, leaving some gaps.

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 perfectly concise with three tightly packed sentences that each earn their place: states the core functionality, provides API correspondence, and specifies authorization requirements. It's front-loaded with the primary purpose and wastes no 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 list/read operation with no annotations and no output schema, the description provides good coverage of purpose, behavior, and authorization. However, it doesn't describe the return format (what a 'station' contains) or pagination mechanics beyond mentioning 'paginated', leaving some contextual gaps for the 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?

The schema description coverage is 100%, providing complete parameter documentation. The description adds no additional parameter semantics beyond what's in the schema (it doesn't explain filtering/sorting mechanics or provide examples). With high schema coverage, the baseline score of 3 is appropriate as the description doesn't enhance parameter understanding.

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 ('Gets') and resource ('list of stations') with specific operational characteristics ('paginated, filtered, and sorted'). It distinguishes from siblings like 'getStation' (singular retrieval) and 'listStationGroups' (different resource type), providing precise scope differentiation.

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

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

The description explicitly states when to use this tool ('Gets a paginated, filtered, and sorted list of stations') and mentions the required scope ('stations:read'), giving clear context for usage. However, it doesn't explicitly mention when NOT to use it or name specific alternatives among the many sibling tools, which prevents a perfect score.

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

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

With no annotations provided, the description carries the full burden. It discloses the required scope ('tables:read') and marks it as read-only, which is helpful for understanding permissions and safety. However, it doesn't describe behavioral traits like pagination, rate limits, error handling, or the format of returned aggregations, leaving gaps in operational 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 highly concise and front-loaded, with every sentence adding value: it states the action, resource, API endpoint, required scope, and read-only nature without any wasted words. The structure is efficient 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?

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is minimally complete. It covers the purpose, scope, and safety but lacks details on output format, pagination, or error behavior. With no output schema, the description should ideally explain what 'aggregations' are returned, but it doesn't, leaving some operational 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?

Schema description coverage is 100%, so the schema already documents the single parameter 'tableId' fully. The description doesn't add any meaning beyond what the schema provides (e.g., it doesn't explain what constitutes a valid tableId or how to obtain it). Baseline score of 3 is appropriate as the schema handles the parameter documentation adequately.

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 ('Lists') and resource ('aggregations for a Tulip Table'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'getTableAggregation' or 'runTableAggregation', which would require more specific scope clarification.

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 mentioning the required scope ('tables:read'), but doesn't provide explicit guidance on when to use this tool versus alternatives like 'getTableAggregation' (for a single aggregation) or 'runTableAggregation' (to execute an aggregation). The context is clear but lacks sibling differentiation.

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 effectively adds context by stating the HTTP method ('GET'), implying read-only behavior, and specifying an authorization requirement ('tables:read' scope). The '[READ-ONLY]' tag reinforces safety, though it doesn't detail response format or pagination.

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 front-loaded with the core purpose, followed by technical and authorization details in a single, efficient sentence. Every element (verb, resource, endpoint, scope, read-only note) earns its place without redundancy or 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?

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is reasonably complete. It covers purpose, endpoint, and authorization, though it lacks details on return values (e.g., query format or pagination) and doesn't fully address sibling differentiation, leaving minor gaps.

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

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

Schema description coverage is 100%, so the schema already documents the single parameter 'tableId'. The description doesn't add any meaning beyond what the schema provides (e.g., it doesn't explain what a 'Tulip Table' is or how to obtain its ID), resulting in a 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 clearly states the verb ('Lists') and resource ('queries for a Tulip Table'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'listTableRecords' or 'getTableQuery', which reduces it from a perfect score.

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 includes a prerequisite ('Requires `tables:read` scope'), which provides some usage context. However, it doesn't specify when to use this tool versus alternatives like 'getTableQuery' (for a single query) or 'listTables' (for listing tables instead of queries), leaving gaps in 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 provided, the description carries the full burden and does well by disclosing the required authentication scope ('tables:read') and explicitly marking it as read-only. It also implies pagination behavior through the 'limit' and 'offset' parameters, though it doesn't detail rate limits or exact return formats.

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 extremely concise and front-loaded, with every sentence earning its place: it states the purpose, maps to the API endpoint, specifies the required scope, and notes the read-only nature, all in three brief clauses without any 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?

Given the tool's moderate complexity (list operation with pagination), no annotations, and no output schema, the description is fairly complete. It covers purpose, authentication, and safety, but could improve by hinting at the return format (e.g., a list of records) or error conditions, which would help compensate for the missing 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?

The schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description doesn't add any additional meaning or examples beyond what the schema provides, such as default values for 'limit' or typical usage patterns, meeting the baseline for high 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 specific action ('Lists records') and resource ('of a Tulip Table'), distinguishing it from sibling tools like 'getTable' (which retrieves table metadata) or 'getTableRecord' (which fetches a single record). The mention of the corresponding API endpoint reinforces the specific scope.

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 by specifying the required scope ('tables:read') and indicating it's read-only, which helps identify when to use it. However, it doesn't explicitly mention when not to use it or name alternatives like 'getTableRecord' for single records or 'listTables' for listing tables instead of records.

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 full burden and does well by disclosing the HTTP method ('GET /tables'), required permissions ('tables:read'), and explicitly marking it as read-only. It doesn't mention rate limits or pagination behavior, but covers essential operational 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 extremely concise (one sentence plus a bracketed note) with zero wasted words. It front-loads the core purpose and efficiently includes all necessary additional information (API endpoint, scope, read-only status).

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 retrieval tool with no parameters and no output schema, the description is nearly complete. It covers purpose, API correspondence, authentication requirements, and safety profile. The only minor gap is lack of information about return format or pagination, which prevents a perfect score.

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 tool has zero parameters, and schema description coverage is 100%. The description appropriately doesn't discuss parameters, which is correct for a parameterless tool. It adds value by mentioning the API endpoint and scope requirements beyond the empty 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 specific action ('Retrieves a list') and resource ('all Tulip Tables'), and distinguishes it from siblings like 'getTable' (singular) and 'listTableRecords' (records within tables). It provides precise scope information.

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 explicitly states when to use this tool ('Retrieves a list of all Tulip Tables') and mentions the required scope ('tables:read'), which provides clear context. However, it doesn't explicitly contrast with alternatives like 'getTable' or 'listTableRecords', which would be needed for a perfect score.

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 full burden and adds valuable behavioral context: it discloses the HTTP method (GET), API endpoint, authentication requirement ('users:read' scope), and read-only nature ('[READ-ONLY]'). It doesn't describe pagination, sorting, or response format, but covers core operational traits adequately.

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, dense sentence with zero waste: it states the action, resource, API correspondence, auth requirement, and safety note. Every element serves a purpose, and the structure is front-loaded with 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 operation with 0 parameters and no output schema, the description is reasonably complete: it covers purpose, API mapping, auth, and safety. It lacks details on response format (e.g., array structure) and potential limitations (e.g., pagination), but given the tool's simplicity, these are minor gaps.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description correctly doesn't discuss parameters, maintaining focus on tool behavior. Baseline for 0 params is 4, as it avoids unnecessary parameter explanations.

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 ('Gets') and resource ('list of user groups'), making the purpose unambiguous. It distinguishes from siblings like 'getUserGroup' (singular retrieval) and 'listUserUserGroups' (user-group relationships). However, it doesn't explicitly contrast with 'listAppGroups' or 'listStationGroups', which share similar naming patterns.

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 context by mentioning the required scope ('users:read'), but doesn't provide explicit guidance on when to choose this tool over alternatives like 'getUserGroup' (for single group) or 'listUserUserGroups' (for user-group mappings). No when-not-to-use scenarios or prerequisites beyond authentication are 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?

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it's a read-only operation (indicated by '[READ-ONLY]'), requires specific permissions ('users:read' scope), and maps to a GET API endpoint. This covers safety and authentication needs adequately for a simple 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 front-loaded with the core purpose, followed by technical details (API endpoint, scope, read-only hint) in a single, efficient sentence. Every element adds value without redundancy, making it appropriately sized 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?

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is complete enough. It covers purpose, authentication, and behavioral traits. However, it lacks details on output format or pagination, which could be useful but isn't critical for basic 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?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, maintaining focus on the tool's purpose and behavior, which aligns with the baseline for zero parameters.

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

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

The description clearly states the verb 'Gets' and resource 'list of user roles', making the purpose specific and understandable. It distinguishes from siblings like 'getUserRole' (singular) and 'listUsers', though it doesn't explicitly contrast them. The mention of the API endpoint adds technical specificity.

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 the required scope 'users:read', which suggests when authentication is needed. However, it lacks explicit guidance on when to use this tool versus alternatives like 'getUserRole' or 'listUsers', and doesn't mention prerequisites or exclusions beyond the scope requirement.

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 states the tool is '[READ-ONLY]' and requires a specific scope, which covers safety and authentication needs. However, it doesn't mention potential behaviors like pagination, rate limits, or return format, leaving gaps in transparency for a list 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 extremely concise with three key pieces of information (action, endpoint, scope, and read-only hint) in just two sentences. Every element earns its place without redundancy, making it front-loaded and efficient.

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 (0 parameters, no output schema, no annotations), the description is moderately complete. It covers the core action, endpoint, and scope, but lacks details on output format, pagination, or error handling, which could be relevant for a list tool even with 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 has 0 parameters with 100% coverage, so the schema fully documents the absence of parameters. The description doesn't need to add parameter information, and it correctly doesn't mention any parameters, earning a baseline score of 4 for appropriate 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 the verb ('Gets') and resource ('list of users'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'getUser' or 'listUserGroups', which would require more specific scope information to earn 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 provides some usage context by mentioning the required scope ('users:read'), which implies when authentication is needed. However, it doesn't explicitly state when to use this tool versus alternatives like 'getUser' (for single user) or 'listUserGroups' (for groups), leaving the guidance at an implied level rather than 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively adds context by stating the required scope ('Requires `users:read` scope'), marking it as read-only, and mentioning the corresponding API endpoint. This covers key behavioral traits like authentication needs and safety, though it lacks details on rate limits or error handling.

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 appropriately sized and front-loaded, with the core purpose stated first, followed by API correspondence, scope requirement, and read-only note. Every sentence adds value without redundancy, making it efficient and easy to parse 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 complexity (a read operation with four parameters), no annotations, and no output schema, the description is mostly complete. It covers purpose, scope, and behavioral context well, but lacks details on the output format (e.g., structure of the returned array) and error cases, which could enhance completeness for the 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?

The schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description doesn't add any additional meaning or clarification about the parameters beyond what's in the schema, such as explaining the OData filter syntax in more detail. Thus, it meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Returns an array of user group IDs') and resource ('that the user is currently a member of'), distinguishing it from sibling tools like listUserGroups (which likely lists all user groups) and getUserGroupUsers (which likely lists users in a specific group). The verb 'returns' and the explicit resource scope make the purpose unambiguous.

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

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

The description provides clear context by specifying the required scope ('Requires `users:read` scope') and indicating it's read-only, which helps determine when to use it. However, it doesn't explicitly mention when not to use it or name alternatives among the sibling tools, such as listUserGroups for a broader list or getUserGroupUsers for reverse lookup.

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 effectively adds context beyond basic functionality by stating the required scope ('machines:read') and marking it as '[READ-ONLY]', which clarifies safety and permission needs. However, it lacks details on rate limits, error handling, or response format, preventing a higher score.

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 appropriately sized and front-loaded, with every sentence earning its place: it states the purpose, specifies the API endpoint, notes the required scope, and indicates read-only behavior. There is no wasted text, making it highly efficient and well-structured.

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

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 nested objects) and high schema coverage, the description is mostly complete. It covers purpose, scope, and safety, but lacks an output schema, so it doesn't explain return values like archive status details. For a read-only tool with simple inputs, this is a minor gap.

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% description coverage, with the 'jobId' parameter clearly documented. The description adds no additional meaning beyond what the schema provides, such as explaining the job ID's origin or format. Thus, it meets the baseline score of 3, as 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 clearly states the tool's purpose with a specific verb ('Retrieves') and resource ('machine activity archive status'), making it understandable. However, it doesn't explicitly differentiate from sibling tools like 'listStations' or 'listMachineTypes', which might also involve machine-related data retrieval, so it falls short of a perfect score.

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 specifying a required scope ('machines:read') and referencing a job ID, suggesting it's for checking archive status after a job. However, it doesn't provide explicit guidance on when to use this tool versus alternatives like 'listMachineTypes' or general data retrieval tools, leaving some ambiguity.

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 adds value by specifying the required scope ('tables:read') and marking it as read-only, which clarifies safety and permission needs. However, it lacks details on rate limits, error handling, or what the aggregation output looks like, leaving gaps for a tool with 7 parameters.

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 front-loaded with the core purpose and includes essential details like scope and read-only status in a single, efficient sentence. There's no wasted text, though it could be slightly more structured by separating scope from behavioral notes.

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 complexity (7 parameters, no output schema, no annotations), the description is moderately complete. It covers purpose, scope, and safety but lacks output details, error handling, and differentiation from siblings. This is adequate for a read-only operation but leaves the agent guessing about results and alternatives.

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 all parameters thoroughly. The description adds no additional parameter semantics beyond what the schema provides, such as examples of function usage or filter interactions. This meets the baseline for high schema coverage but doesn't enhance understanding.

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 ('Runs an aggregate function') and resource ('on a table field'), making the purpose understandable. However, it doesn't differentiate this tool from sibling tools like 'getTableAggregation' or 'listTableAggregations', which appear related but have unclear distinctions based on their names 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 implies usage by specifying the required scope ('tables:read') and marking it as read-only, which provides some context. However, it doesn't explicitly state when to use this tool versus alternatives like 'getTableAggregation' or 'listTableAggregations', leaving the agent to infer based on naming conventions.

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