TrueClicks

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

The description discloses the read-only nature ('Get') and the output format (JSONL), which goes beyond the provided annotations (readOnlyHint=true, destructiveHint=false). It also transparently explains the account ID field naming convention, which could otherwise be ambiguous. No contradictions with annotations.

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

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

The description is concise (two sentences) and well-structured. It front-loads the primary purpose ('Get all accounts'), then adds necessary details about output format and ID resolution. No redundant or vague wording.

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

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

For a tool with no parameters and no output schema, the description is complete. It specifies what is returned (accounts with fields), the format (JSONL), and how to use the results (accountId resolution). It fully equips the agent to invoke the tool correctly.

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 is empty (0 parameters), so the baseline is 4. The description doesn't need to explain parameters, and it adds additional context about the output and ID usage. No parameter-related gaps exist.

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: 'Get all accounts' with specific output details (JSONL format and fields). It distinguishes itself from sibling tools by indicating this is the account listing tool, and the mention of resolving account IDs for other calls further clarifies its role.

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 tells when to use this tool: 'use this to resolve account ids before calling them' and clarifies the distinction between Id and ClientCustomerId field. This provides direct guidance for the agent, making it clear this is a prerequisite step for tools requiring accountId.

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

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

The description discloses the output format (JSONL) and row semantics (one per assignment), which goes beyond the readOnlyHint annotation. It does not mention potential edge cases like large result sets, but for a simple read operation this is adequate.

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

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

The description is a single, concise sentence that directly states the purpose and output format. No unnecessary words 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?

The description is sufficient for a simple list tool, but it does not specify the exact fields present in each row (e.g., account ID, label name). This minor gap is acceptable given the typical expectation of such a tool, but a bit more detail would make it fully 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 sole parameter 'accountIds' is fully documented in the schema description, including its optionality, meaning, and default behavior. The reference to the 'numeric Id field' from the account listing adds helpful context.

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

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

The description clearly states the tool retrieves account labels as JSONL, with a specific resource (account labels) and action (Get). It is distinct from sibling tools like 'account' which likely lists accounts, and 'account_label' is unambiguous.

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

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

The description implies usage for retrieving account-label assignments, but does not explicitly contrast with alternatives or state when to prefer this tool over others. However, given the sibling set, the purpose is fairly evident, so it is not misleading.

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

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

The safe read-only behavior is already captured by readOnlyHint=true and destructiveHint=false, so the description doesn't need to cover those. It adds useful behavioral context beyond the annotations: results are 'latest,' formatted as Markdown, aggregated per account, and represent a high-level roll-up across all audit rules. It does not contradict the annotations.

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

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

The description is just two sentences with clear front-loading of the action, target resource, and output format. There is no filler, and the phrase 'suitable for direct AI consumption' adds relevant guidance rather than being padding.

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 one-parameter, read-only tool with 100% schema coverage and no output schema, the description covers the main points an agent needs: what to call it for, the result format, and the aggregation level. It's slightly sparse on detail of what the Markdown summary actually contains, but the high-level roll-up context makes it sufficient for the intended use.

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

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

Schema description coverage is 100%, and the accountIds parameter already carries the specific true-natural language about TrueClicks account IDs, the ID type nuance, and the empty-array behavior. The description adds no new parameter semantics, so the baseline score of 3 applies.

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

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

The description gives a specific verb+resource ('Get the latest account-aggregated audit results') and states the output format (Markdown summary) and scope (high-level roll-up across all audit rules). This makes it clearly distinct from the per-rule and per-campaign audit siblings, even without naming them.

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

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

The description implies when to use this tool: when an account-level, high-level Markdown summary of audit results is needed. However, it never names or excludes alternatives like audit_rule_result or audit_rule_output_table, so in a list of many audit sibling tools the selection guidance is mostly left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: the exact JSONL block structure ('>>>>> RuleKey:' headers, a JSON Schema line with tooltips and column types, main rows with detail rows nested under 'children'), and the notable behavior that rules with no completed run in the last 30 days contribute no block.

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 dense and well-structured: verb+resource first, then output format, then use case, then the 30-day caveat. Every clause adds unique information—block structure, schema line contents, children nesting, raw-findings purpose, and the no-block condition—with no repetition or filler.

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

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

With no output schema present, the description correctly carries the return-format burden and does so thoroughly (block structure, nesting, per-rule behavior). Minor gaps remain: block ordering across multiple rules, error behavior for invalid rule keys or account IDs, and row ordering are unspecified. For a 4-parameter tool with 100% schema coverage, this is near-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 baseline is 3. The description loosely maps to parameters ('one account' → accountId, 'one or more rules' → ruleKeys) but adds no parameter-level detail beyond what the schema already provides. The schema itself carries the semantic load here.

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

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

The description states a specific verb+resource+scope: 'Get the detailed output rows for the latest completed audit run of one or more rules for one account.' The qualifier 'latest completed' and the 30-day window clearly distinguish this from the sibling audit_rule_output_table_historical, and the output format (multi-block JSONL) is specified in the first sentence.

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

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

The description gives clear usage context: it provides 'the raw findings behind a failing audit rule' and applies to the 'latest completed audit run' with a 30-day window. However, it does not explicitly name alternatives (e.g., audit_rule_output_table_historical for older runs) or state when-not-to-use conditions, so it stops short of the explicit routing a 5 would require.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral detail: it explains the multi-block JSONL structure, that weeks with no completed run contribute no block, and that weekStartDates are Monday start dates. This goes well beyond the annotations and helps the agent anticipate edge cases.

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 paragraph that front-loads the purpose, then details the output format and usage. It is informative without being overly verbose, and each sentence contributes to understanding the tool's behavior. Slightly long but well-organized.

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

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

The tool is complex with multiple parameters and a nested output structure, and no output schema exists. The description fully compensates by explaining the output format, the date format, the rule key example, and the behavior for missing weeks. It provides all necessary information for an agent to call the tool correctly.

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

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

The input schema covers all parameters with descriptions (100% coverage), including the example rule key and the optional limit. The description does not introduce new semantic information about parameters beyond the schema, so it meets the baseline of 3 without adding extra 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 tool retrieves detailed output rows for audit rules across multiple historical weeks, specifying the exact output format (multi-block JSONL) and its intended use (comparing findings over time). It distinguishes itself from the sibling 'audit_rule_output_table' by emphasizing historical multi-week data.

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 the use case 'Use to compare how findings changed over time', providing clear context for when to invoke it. However, it does not explicitly mention when not to use it or directly contrast with the non-historical sibling, leaving some inference to 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?

The description adds useful behavioral details beyond the annotations, such as 'Never returns disabled rules', grouping by type, and historical column appending. The readOnlyHint annotation already covers safety, and the description does not contradict it.

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 information-dense but not bloated. It follows a logical flow: result type, filtering, grouping, columns, and optional historical behavior. Every sentence adds useful information.

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

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

There is no output schema, so the description rightly explains return format and key columns. It is complete enough for typical use, though it omits edge-case behavior like empty accountIds, ordering, pagination, or error conditions.

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 already covers all parameters with 100% coverage, and the description adds extra behavioral meaning, especially for numberOfWeeks ('historical weekly columns are appended, most recent first') and onlyFailed. It reinforces but does not merely echo the schema.

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

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

The description clearly states the verb ('Get'), the resource ('account-level audit rule results'), and the output format ('Markdown summary'). It also distinguishes itself as account-level, which helps separate it from campaign-level or output-table sibling tools.

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?

Parameter usage is explained well (accountIds filtering, onlyFailed, numberOfWeeks), but the description does not explicitly say when to choose this tool over related siblings like audit_account_result, audit_rule_output_table, or audit_rule_result_campaign. Guidance is 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?

Beyond the read-only annotation, the description discloses the exact behavior regarding historical weeks, how results are filtered, and the meaning of cell values like 'Rows (0)' and '-'. It provides substantial operational details that an agent would need to interpret the output correctly.

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 verbose and repeats inclusion/exclusion logic in multiple places. While it is well-structured and front-loaded, the redundant clarifications could be condensed without losing meaning, making it less concise than ideal.

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

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

The description covers the output format (Markdown summary), the inclusion rules, and the interpretation of historical data. It does not mention pagination or error handling, but for a read-only reporting tool, the provided context is largely sufficient.

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

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

All three parameters have descriptions that go beyond type definitions. For example, campaignIds explains the filtering behavior and the null/empty default, and numberOfWeeks clarifies the default and its effect. This provides clear semantic value beyond the schema.

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

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

The description clearly states that the tool gets campaign-level audit rule results as a Markdown summary, and explicitly distinguishes it from account-level or rule-level results. It also defines the inclusion and exclusion criteria, making the purpose unambiguous.

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

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

The description explains the scope (single account, campaign-specific rules) and the inclusive/exclusive logic, but it does not explicitly compare this tool to sibling tools like audit_rule_result or audit_account_result. The selection is implied by the title and content, but not directly 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?

The description adds substantial behavioral detail beyond the readOnlyHint and destructiveHint annotations: it specifies JSON Lines output, a first-line schema marker, nested per-row objects, snake_case GAQL field names, enum values returned in Google format, and detailed error messages on API failure. This is especially valuable given the lack of an output schema, though it does not cover rate limits, timeouts, or authentication requirements.

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

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

Two sentences carry the full payload: purpose first, then output format and error behavior. There is no filler, no repetition of schema text, and the most important scoping information is front-loaded.

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

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

For a tool with 8 parameters and no output schema, the description does a good job explaining what the caller receives (JSON Lines schema line plus rows, snake_case fields, enum values) and what happens on failure. Minor gaps remain, such as whether results are paginated or batched and what occurs with zero rows, but these are not critical given the schema's parameter 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?

Input schema coverage is 100%, so each parameter already has a meaningful description. The tool description adds no per-parameter semantics beyond confirming the query is structured GAQL and that output field names are snake_case; it does not elaborate on accountId meaning, date pairing rules, or predicate/orderBy syntax beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific action and resource: 'Execute a structured Google Ads GAQL query for one account.' This clearly distinguishes it from sibling tools like google_ads_reports_list or google_ads_report_columns by naming the platform and execution verb, so an agent can select it without opening schemas.

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

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

Usage context is implied: use this when you need to run a GAQL report query for a single Google Ads account. However, the description never explicitly states when to choose this over siblings, nor gives negative guidance such as 'not for listing available reports' or 'not for fetching column metadata.' The one-account scope is useful but not a full when-to-use/when-not-to-use statement.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds that the output is 'raw CSV', providing specific behavior detail beyond the annotations. It does not mention error handling or side effects, but the read-only nature is well-covered.

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, focused sentence that immediately identifies the action, scope, and output format. It is concise and well-structured without unnecessary 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 metadata retrieval tool with one parameter, the description is largely complete. It covers the main purpose and output format, though it could hint at how report names are sourced or what the CSV contains (e.g., headers) for additional clarity. Minor gaps do not hinder basic usage.

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

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

The schema provides a 100% description for the reportName parameter. The tool description essentially repeats this information without adding new details such as allowed values, format constraints, or how to obtain valid report names. No additional semantic value is provided.

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 (getting column/field definitions) and the resource (a given Google Ads report) and specifies the output format as raw CSV. It effectively differentiates itself from sibling tools like google_ads_reports_list and google_ads_execute_report by focusing on metadata 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 does not explicitly state when to use this tool versus alternatives. While the purpose is self-evident and the name suggests it is for retrieving column definitions, there is no direct guidance on use cases or contrast with sibling tools. This is adequate but not explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is known. The description adds valuable behavioral context by specifying the output format ('raw CSV') and the content (report/resource names in the GAQL schema), which goes beyond the annotations. No contradictions detected.

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

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

The description is a single, well-structured sentence that front-loads the primary action ('Get the list'), then specifies the content and output format. Every word contributes meaning, with no filler or redundancy.

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

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

For a no-parameter, read-only list tool, the description is fully complete. It states what the tool returns (list of report definitions) and the format (raw CSV), which is all an agent needs to invoke it correctly. The lack of an output schema is compensated by this explicit return description.

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?

This tool has zero parameters, and the schema description coverage is 100% (vacuously). Per the rubric, a baseline of 4 is appropriate. The description does not need to explain parameters since there are none, and it correctly avoids inventing any.

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

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

The description clearly states the tool's function: retrieving a list of available Google Ads report definitions (report/resource names) as raw CSV. It specifies the resource type and output format, making the purpose unambiguous. However, it does not explicitly distinguish itself from sibling tools like google_ads_report_columns, though the term 'report definitions' implies a difference.

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—when you need the list of report definitions—but does not explicitly state when to use this tool versus alternatives such as google_ads_execute_report or google_ads_report_columns. It provides clear context but no exclusions or comparative 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable context: the output is JSON Lines with a schema-first line, records are returned verbatim with nested structures preserved, the schema is inferred from data (open-world), and the act_ prefix/token are auto-added. This goes beyond annotations and clarifies behavior without any contradiction.

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

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

The description is three sentences, front-loaded with the core purpose and output format, then providing Graph API context and the auto-added prefix note. It is efficient with no fluff, though the second sentence could be slightly tightened without losing meaning.

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

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

For a generic query executor with open-world semantics, the description covers the essential aspects: what it does, output format, query syntax, auto-added credentials, and the read-only nature (via annotations). It does not mention error handling or rate limits, but these are not critical for a read-only tool. The description is sufficient for an agent to call it correctly.

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

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

The input schema has 100% coverage with detailed descriptions for both parameters, including examples and constraints (e.g., do not include act_ prefix, accountId is TrueClicks id). The description reiterates the auto-added prefix/token but adds little new semantic meaning beyond the schema. Baseline 3 is appropriate because the schema already carries the burden.

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 (execute a Meta Marketing API query), the resource (Meta/Facebook), and the output format (JSON Lines with schema). It distinguishes from sibling execute_report tools by explicitly naming Meta and contrasting with the Google and Microsoft siblings in the tool list. The purpose is unambiguous and specific.

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

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

The description implies usage for Meta ads via the name and explicit 'Meta (Facebook) Marketing API' phrasing, and it provides guidance on query syntax and what to exclude (act_ prefix, token). However, it does not explicitly mention alternatives (e.g., 'use google_ads_execute_report for Google Ads'), so the guidance is clear but not fully explicit about when not to use this tool. Sibling names make the platform distinction obvious.

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

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

Annotations already declare readOnly and non-destructive. The description adds valuable behavioral context: the JSON Lines structure with a schema marker, autodetected value types, and the fact that it returns raw configuration data rather than time-bound metrics. This goes beyond the annotations without contradicting them.

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

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

Two well-structured sentences with no fluff. The first sentence delivers the core purpose and output format, the second clarifies scope and contrast. Every clause earns its place.

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

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

For a bulk query tool with no output schema, the description thoroughly explains the return format and its non-performance nature. Minor omissions like pagination or limits are acceptable given the tool's simplicity and the schema coverage.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description adds minimal parameter-specific meaning, but the baseline of 3 is appropriate since the schema fully covers required inputs.

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 executes a Microsoft Ads bulk query for a single account and specifies the output format (JSON Lines with a schema line). It explicitly contrasts with time-bound performance metrics, distinguishing this from siblings like ms_ads_execute_report_query.

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 usage context by stating this is for entity/configuration snapshots without date range or aggregation, implying it should not be used for performance metrics. Though it doesn't name the alternative tool explicitly, the distinction is actionable.

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

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

Annotations already establish read-only and non-destructive behavior. The description adds meaningful behavioral detail by documenting the JSON Lines output contract: a schema-carrying first line, one JSON object per row, and autodetected value types. It does not mention pagination, limits, or failure modes, but for a read-only report query the added detail is strong.

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 dense but efficient: three sentences each carry real value, covering the output contract, mandatory parameters, and scope exclusions. The information is front-loaded and there is no filler.

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

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

The description compensates well for the missing output schema by specifying the exact response shape and compensates for sibling ambiguity by scoping metric reports versus entity snapshots. Minor gaps remain around pagination, limits, and error handling, but the tool is adequately documented for correct invocation.

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

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

Schema coverage for parameters is 100%, so the baseline is 3. The description mostly reiterates that startDate, endDate, and reportAggregation are required and time-bound, without adding significant new meaning beyond the already-detailed schema descriptions for accountId, report, columns, and predicates.

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

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

The description states the exact action (execute), the resource (Microsoft Ads performance report query), and the scope (one account over a date range). It also explicitly distinguishes itself from entity/configuration snapshots, differentiating it from sibling report-list and bulk-query tools.

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

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

The description gives clear when-to-use guidance: performance/metric reports bound by a date range. It also states what it is not for (entity/configuration snapshots without metrics or date range), but it does not name the specific sibling tool to use instead, so it falls just short of the strongest routing 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?

The readOnlyHint annotation already indicates no side effects. The description adds the concrete output format (CSV, one column name per row), which helps set expectations. No behavioral contradictions exist.

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 very concise, with no redundant wording. It communicates the resource, output format, and downstream usage in one short paragraph.

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 single-parameter read-only tool, the description is complete: it states what is returned, in what format, and how the result should be used. No output schema is provided, but the CSV format is explicitly described.

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 property description fully explains that 'report' is the name of a Microsoft Ads report and one of the available report names, linking conceptually to the reports list tool. This adds enough context beyond the raw parameter name.

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 gets selectable columns for a Microsoft Ads report, specifies CSV output format (one per row), and explains their purpose as valid entries for the report query's 'columns' argument. This distinguishes it from sibling tools like ms_ads_reports_list and ms_ads_execute_report_query.

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

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

The description implies the tool should be used to discover valid column names before constructing a report query's 'columns' argument. It does not explicitly mention alternatives or when not to use it, but the reference to the query's columns argument gives clear practical 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds valuable context about the CSV format and the meaning of the 'Type' column, including that the two types use different naming conventions. This goes beyond annotations and helps the agent interpret the output correctly.

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

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

The description is two sentences, front-loaded with the core purpose and output format, then explains the two types. Every sentence earns its place; no wasted words. It is concise and well-structured.

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

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

For a listing tool with no parameters and no output schema, the description covers everything an agent needs: it specifies the CSV format, the columns, and the meaning of the two types, including the note about naming differences. No critical information is missing.

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, so the schema coverage is trivially 100%. With no parameters to document, the description does not need to add anything. The baseline for zero parameters is 4, and the description correctly focuses on output semantics rather than 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 states a specific verb ('Get') and resource ('available Microsoft Ads reports') and defines the output as CSV with two named columns. It further distinguishes the two report types ('Report' vs 'Bulk') with their meanings, clearly differentiating from sibling tools like ms_ads_report_columns (which lists columns) and ms_ads_execute_report_query (which executes queries).

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

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

The description gives clear context about what the tool returns and the semantics of the two types, which helps an agent decide when to use it. However, it does not explicitly mention alternatives or when not to use it. The distinction between listing reports and executing them is implied but not stated, so a small gap remains.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds material behavioral context: perfmon stores no history so the result is current state, the meaning of threshold vs fluctuation alerts, and the exact field semantics in each output line. This goes well beyond the structured metadata.

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 dense but purposeful; the first sentence states the core behavior, and later sentences define alert types, output line fields, and parameter defaults. It is longer than average, but the length is justified because there is no output schema to document the return shape.

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 read-only alert-listing tool with no output schema and no required parameters, the description documents the output format (JSONL), field meanings, the two alert categories, entity scoping, and the priority filter. An agent has enough information to invoke it correctly and interpret the response without supplemental 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 covers 100% of the four parameters, and the description adds value by explaining defaults ('Defaults to High + Critical only'), the threshold/fluctuation subtype semantics, and the campaignIds scoping rule. It also clarifies that PerfmonId and PerfmonDefinitionMetricId identify the underlying per-campaign metric rows.

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

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

The description opens with a specific verb and resource: 'Get the currently triggered perfmon alerts (both threshold and fluctuation) for one or more accounts as JSONL.' It names both alert subtypes, so an agent can immediately tell exactly what is returned and can distinguish it from sibling tools such as perfmon_alert_output_table or target_pacing.

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

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

The description gives explicit usage direction: defaults to High + Critical unless minPriority is widened, metricType narrows to one kind, and campaignIds is positioned as 'Use this ONLY to focus on / analyze specific campaign(s)'. It does not name an alternative sibling, but the 'currently triggered ... no history' wording makes the use case clear.

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

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

The description adds useful behavioral context beyond the read-only annotation: it specifies the output format (JSONL), the row structure (one per campaign per date range), and the meaning of the DateRange column. Since annotations already indicate read-only and non-destructive behavior, the additional detail is appropriately supplementary.

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

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

Two sentences with no redundancy. The main purpose is front-loaded, followed by precise identification details and output semantics. Every clause adds value; no filler or unnecessary repetition.

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

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

For a tool with five parameters and no output schema, the description gives sufficient context: purpose, identification method, output format, row granularity, DateRange meaning, and filtering option. It does not enumerate possible output fields, but that is not essential for invoking the tool correctly.

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

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

Schema coverage is 100% with each parameter already described. The description restates where PerfmonId and PerfmonDefinitionMetricId come from (matching schema text) and clarifies the campaignIds filter, but these are marginal additions. The primary new information (DateRange) pertains to the output, not parameters. Baseline of 3 is appropriate given 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?

Clearly states the action ('Get') and the resource ('per-campaign metric rows behind a triggered perfmon alert'), specifying the output format (JSONL). Distinguishes from sibling alert-view tools by indicating this returns the underlying rows, not the alert definitions.

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

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

Provides explicit instructions on how to identify the alert (PerfmonId, PerfmonDefinitionMetricId, accountId) and how to filter (campaignIds). Explains the DateRange semantics for interpreting rows. While it doesn't explicitly contrast with sibling tools, the context of sibling names (perfmon_fluctuation_alert, perfmon_threshold_alert) makes the use case clear.

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

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

The readOnlyHint and destructiveHint annotations already cover the non-mutating behavior, and the description consistently describes a read operation. It adds useful output-format context but no conflicting behavior.

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

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

The description is compact but information-dense, using two sentences to convey purpose, scope, output format, target categories, and included fields. No unnecessary filler.

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

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

With no output schema, the description compensates by listing the fields contained in each line. It lacks details on error conditions or ordering, but for a simple read-only getter it is sufficiently 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 only parameter, accountIds, is fully described in the schema with its optionality, meaning, source of valid values, and default behavior when omitted. No ambiguity remains.

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

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

Clearly states it retrieves current active pacing and efficiency targets as JSONL, and explicitly distinguishes the scope from budget-only targets. The resource and purpose are 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?

Describes what the tool covers and that it returns active targets, but does not explicitly compare it to sibling tools such as target_pacing_all or state when one should be preferred over the other.

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

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

Annotations already indicate read-only and non-destructive behavior, and the description reinforces this by describing a listing/retrieval operation returning JSONL. It also clarifies date-scope behavior, which adds transparency beyond the annotations.

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

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

The description is compact and well-structured, front-loading the core purpose and then clarifying scope and limitations. No redundant or filler content.

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?

Sufficiently complete for a read-only listing tool: it explains output format, coverage, and date restriction. It does not describe a return schema, but none is provided, and the operation is simple enough that this is not a critical 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 single parameter accountIds is fully described in the schema including default and omission behavior. The description reinforces that omitting returns all accounts, adding practical meaning beyond the schema text.

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

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

Clearly states it gets all pacing and efficiency targets as JSONL, explicitly covering Pacing and Efficiency types. It distinguishes itself from the sibling target_pacing tool by saying 'all' and by describing scope across periods and the 365-day limit.

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

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

Provides useful usage context: not just budget, includes pacing and efficiency targets, limited to last 365 days plus current/future. It implies this is the broader list compared to target_pacing, though it does not explicitly name the sibling alternative or when to choose one over the other.

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

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

The description aligns with the readOnlyHint annotation and adds useful behavioral details (JSONL format, time limit) without contradicting the annotations. No side effects are mentioned, which is consistent with the read-only nature.

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

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

The description is a single, concise sentence that directly conveys the tool's purpose and key constraints without unnecessary detail.

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

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

The description provides enough context for the tool's operation, including output format and time limit. Since there is no output schema, it does not need to explain return values. Minor details like pagination are omitted but not critical for basic usage.

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

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

The only parameter, accountIds, has a full description in the schema, so the tool description does not need to add more. The schema coverage is 100%, meeting the baseline for this dimension.

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

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

The description clearly states the verb 'Get', the resource 'tasks', and the output format 'JSONL', which distinguishes it from other tools. It also specifies a time limit, making the purpose unambiguous.

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

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

The description provides clear context about the tool's behavior (JSONL output, 365-day limit) but does not explicitly state when to use it versus alternatives. However, since no sibling tool performs a similar task-listing function, the intended use is implicit and clear.

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

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

The read-only nature is already covered by annotations, and the description adds behavioral context by specifying JSONL output and the 'no account restriction' scoping. It does not mention pagination or rate limits, but those are not required given the annotation coverage.

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 brief, but the phrase 'returns rows only for a connector with no account restriction' is vague and confusing. It introduces ambiguity without adding clear value, so not every sentence earns its place.

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

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

The tool is simple, but the contradictory statements about account filtering leave the overall behavior unclear. The description would be complete if it clarified whether accountIds is accepted and how it affects results; without that, it is not reliable.

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 fully documents accountIds as an optional filter, but the description explicitly says the data is 'not account-filterable'. This directly contradicts the parameter's purpose and undermines the agent's ability to decide whether or how to pass accountIds.

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

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

The description clearly identifies the resource as the customer's users, the action as getting/listing them, and the output format as JSONL. It also distinguishes it as customer-level data, separating it from account-level tools.

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

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

It states that the data is customer-level and not account-filterable, giving clear scope and exclusions. However, it does not explicitly name an alternative tool such as user_my_accounts, so it falls short of fully explicit alternative 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?

Annotations already indicate read-only, and description adds no extra behavioral details but clarifies output format (JSONL).

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

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

Two sentences with no redundancy, all information relevant.

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?

Explains the concept of My Accounts, the output format (JSONL, one row per selection), and the optional filter; sufficient despite lack of 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 fully describes accountIds with optionality and meaning; description only repeats the filter behavior, so no additional meaning beyond 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?

States a specific verb ('Get') and resource ('each user's selected My Accounts'), distinguishes from sibling tools like 'account' and 'user' by clarifying it's a per-user preference, not access-permission.

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

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

Provides context on when to use (when you need user preferences, not permissions) and mentions optional filtering by accountIds, but does not explicitly name alternative tools for comparison.

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