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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-destructive operation. The description adds only the entity types and patch scope, which are also evident from the schema. It does not disclose any additional behavioral traits such as output format or error handling, but this is not a 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 a single, front-loaded sentence with no redundant words. It efficiently communicates the tool's primary purpose and scope.

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 comparison tool with 4 parameters and no output schema, the description provides a basic overview but lacks important context such as what the comparison result looks like or how it differs from the sibling diff_versions. The absence of output schema and the presence of ambiguous siblings leave the description incomplete for an agent deciding among multiple similar tools.

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 each parameter. The description adds minimal semantic value beyond enumerating the supported kinds, which the schema already captures via the 'kind' enum. It does not explain parameter interactions or formats beyond what the schema provides.

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 compares an exact API, event, enum, structure, widget, or system between two retail patches. It uses a specific verb ('compare') and names the resource type and version scope. It does not explicitly distinguish this from sibling tool diff_versions, so it misses the top 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 use when comparing an exact entity between versions, but gives no explicit guidance on when to use this tool versus the sibling diff_versions or other lookup tools. No alternatives or exclusions are mentioned, leaving the agent to infer the appropriate context.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the safety profile is well covered. The description adds the three change categories (added/removed/structurally changed) and mentions optional filters, which clarifies the semantic scope and output content beyond what annotations provide.

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

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

The description is a single sentence that is front-loaded with the action ('List') and scope ('APIs ... between two retail patches'), with no filler. It efficiently conveys the core purpose and optional filters.

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?

While there is no output schema, the description sufficiently conveys what the tool returns (a list of changes categorized as added, removed, or structurally changed). Parameters and safety are well covered by the schema and annotations, leaving only minor ambiguity about the exact output 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?

Schema description coverage is 100%, so each parameter already has its own description. The description mentions 'kind and namespace filters' which directly maps to two parameters, but does not add significant meaning beyond the schema's detailed property descriptions.

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

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

The description uses a specific verb 'List' with the resource 'APIs' and scopes it to 'between two retail patches', clearly distinguishing it from sibling tools like list_versions or compare_api by focusing on added/removed/structurally changed changes. This makes the tool's purpose immediately obvious.

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

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

The description implies a usage context (comparing two retail patches) but does not explicitly state when to prefer this over compare_api or other alternatives. No exclusions or alternative tool guidance is provided, so the agent must infer usage from the description and sibling tool names.

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 idempotentHint=true, covering the read-only safety profile. The description adds that the tool scans retail patches and filters for changes (appeared, disappeared, or changed structure), which is useful context, but it does not describe output ordering, pagination, or the precise meaning of 'changed structure'.

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

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

The description is a single sentence that front-loads the primary action and scope. 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 read-only history tool with fully described parameters and safe annotations, the description adequately conveys the tool's scope and output (list of patches where changes occurred). It could optionally mention default version behavior or output format, but these are not critical gaps given the schema and annotations.

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

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

With schema description coverage at 100%, each parameter already has meaningful documentation. The description reinforces the 'name' parameter by saying 'exact API' but adds no new semantic detail beyond what the schema provides, so it meets the baseline for a fully covered schema.

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

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

The description clearly states the tool's function: to show retail patches where a single exact API appeared, disappeared, or changed structure. It uses a specific verb ('Show') and resource ('retail patches'), and distinguishes itself from sibling tools like diff_versions or list_versions by focusing on historical changes of one API rather than comparisons or version listings.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives such as diff_versions, compare_api, or lookup_api. The use case is implied by the description but no selection criteria or exclusions are stated, leaving the agent to infer when this is the right choice.

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, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by specifying exactly what the report includes and implies version resolution behavior ('resolved'). No contradiction with annotations, though return format and error handling are not disclosed.

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

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

The description is a single, front-loaded sentence that concisely lists all key deliverables: resolved dataset, upstream commit, entry counts, archive coverage. No waste 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 simple read-only tool with one optional parameter and strong annotations, the description is sufficiently complete. It clearly outlines what the tool reports, which is especially valuable since there is no output schema. The sibling list confirms this tool is distinct and focused.

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 'version' is fully documented in the schema with its description 'Retail patch, full client build, build number, or latest.' Schema coverage is 100%, so the description adds no additional parameter semantics, warranting the baseline score of 3.

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

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

The description clearly states the tool's purpose: 'Report the resolved WoW retail dataset, upstream commit, entry counts, and archive coverage.' The verb 'Report' and specific resource distinguish it from sibling tools like lookup_api or get_widget_methods.

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

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

The description implies usage when dataset info is needed (e.g., checking upstream commit or entry counts). It provides clear context but lacks explicit exclusions or references to alternatives like list_versions. However, no misleading guidance is present.

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 the tool as read-only and non-destructive, so the description does not need to restate that. It adds some context by noting the result includes 'all values and metadata' and is scoped to 'one retail patch', but does not detail return format 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 a single, well-structured sentence that immediately communicates the tool's core function. No unnecessary words or redundant 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?

For a simple read-only getter with two parameters and no output schema, the description covers the essential purpose and scope. It could be slightly more complete by explaining the default behavior of the version parameter, but the annotation and schema fill in the 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 already provides full descriptions for both parameters (name and version), covering 100% of the schema. The description's mention of 'one retail patch' loosely aligns with the version parameter but does not add additional meaning beyond the schema.

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

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

The description clearly states the tool retrieves a specific WoW enumeration along with all its values and metadata for a given retail patch. The verb 'Get' and the resource 'enumeration' make the purpose explicit, and it distinguishes itself from sibling tools like get_namespace or get_dataset_info.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It implies use for retrieving enumerations, but does not mention any exclusions or alternative tools, such as search_api or lookup_api.

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 idempotentHint=true. The description adds useful context about version scoping ('in one retail patch') and return content ('payload, and restrictions'), but does not disclose edge cases like missing events or error behavior, so it is moderate.

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

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

A single, front-loaded sentence with no filler. Every word contributes to the purpose and scope, 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?

For a simple read-only lookup with two parameters and no output schema, the description adequately covers the core purpose, version scoping, and hint at return content. It lacks return format details or error handling, but these are less critical given the tool's simplicity.

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% (both name and version have descriptions). The description's 'in one retail patch' echoes the version parameter but adds no extra detail beyond the schema, so it meets the baseline.

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

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

The description uses the specific verb 'Get' with a precise resource ('exact WoW frame event') and scope ('payload, and restrictions in one retail patch'). It clearly distinguishes from sibling tools like search_api or get_enum.

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

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

No guidance is provided on when to use this tool versus alternatives such as search_api or lookup_api. It does not mention exclusions, prerequisites, or alternative contexts.

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 mark the operation as read-only, idempotent, and non-destructive. The description adds the scoping detail of 'exact namespace' and 'one retail patch', but it does not disclose behavior around missing namespaces, empty results, or output 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 a single well-structured sentence that clearly conveys the action and scope without any redundant or extraneous information.

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

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

Given the strong annotations and simple parameter schema, the description covers the core purpose. However, since no output schema exists, it could benefit from a hint about the return structure or empty-result behavior, making it slightly incomplete.

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

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

The input schema already fully describes both parameters ('namespace' with examples, 'version' with accepted formats). The description does not add additional semantic meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's action ('List') and target resource ('functions, events, types, and systems') with an explicit scope ('exact namespace in one retail patch'). This distinguishes it from sibling tools that search or look up individual items.

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 use for exact namespace queries and version-specific lookups, but it does not explicitly state when to prefer this over siblings like search_api or lookup_api, nor does it mention exclusions or conditions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the behavioral detail that results are scoped to 'one retail patch', implying version-specific output, but does not disclose return structure or edge cases like missing widgets. This is consistent with annotations, so a 3 is appropriate.

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, compact sentence that conveys the core function without unnecessary words. It is appropriately front-loaded with the verb 'Get'.

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

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

Given the tool has three parameters and no output schema, the description provides only a basic outline. It omits guidance on return format and how to choose between this and sibling lookup/search tools, making it adequate but not comprehensive.

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 are fully documented in the schema (100% coverage), including descriptions for name, version, and include_inherited. The description does not add any additional parameter semantics; the phrase 'in one retail patch' loosely maps to the version parameter but adds no new information beyond the schema.

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

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

The description uses the verb 'Get' and identifies the resource as 'ScriptObject or FrameXML intrinsic widget and its public methods', which clarifies it focuses on widget methods rather than general API lookups. It distinguishes from sibling tools like get_enum or get_event by the widget-specific scope, but the phrasing 'widget and its public methods' is slightly ambiguous about whether it returns the widget itself or just methods.

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

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

The description provides no guidance on when to use this tool versus alternatives such as lookup_api or search_api. It does not mention any exclusions or prerequisites, leaving the agent to infer usage solely from the tool name and schema.

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

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

Annotations already cover safety (read-only, idempotent, non-destructive). The description adds context about scope ('every', 'bundled') and the purpose ('before migration comparisons'), which goes 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?

Two concise sentences: the first states what it lists, the second gives usage guidance. No fluff, perfectly front-loaded.

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

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

For a simple parameterless list tool with strong annotations and no output schema, the description fully captures its purpose and when to use it. It's complete for the tool's 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?

There are no parameters, so the description doesn't need to explain them. Baseline for 0 params is 4, and the description doesn't waste space on parameter details.

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

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

The description uses a specific verb ('List') and identifies a distinct resource ('bundled retail patch snapshot, build, date, and source commit'). It clearly differs from sibling tools like diff_versions and compare_api by focusing on listing all snapshots rather than comparing 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?

Explicitly states when to use it: 'Use this before migration comparisons.' It provides a clear context but doesn't mention exclusions or alternative tools directly (though it implies comparisons are separate).

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the tool's scope (types of API objects and patch-specificity) but does not disclose return format or error behavior. With annotations present, a 3 is appropriate.

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

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

The description is a single, well-structured sentence with no filler. It leads with the verb and covers the essential scope. Every word contributes to understanding.

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

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

The tool has a clear purpose, rich annotations, and a fully described schema. Although there is no output schema, the description implies the return of a definition from a specific patch. Some details about output structure are missing, but the description is adequate given the context. Score 4.

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. The description references 'exact' (matching the name parameter) and 'one retail patch' (matching version) but adds no new parameter details. Baseline 3 is correct.

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

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

The description uses a specific verb 'Look up' and clearly specifies the resource: 'exact WoW API function, method, event, enum, structure, widget, or system in one retail patch.' It distinguishes itself from sibling tools like search_api (which implies fuzzy search) and diff/compare by emphasizing 'exact' and 'one retail patch.'

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 implicitly communicates when to use it (for exact lookups in a specific patch), but does not explicitly mention alternatives or exclusions. It provides clear context for its intended use case, so it earns a 4 rather than a 3.

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 and idempotentHint, and the description adds valuable behavioral details: 'Exact and prefix matches rank first' and the explicit scoping to a single retail patch. This goes beyond the minimal burden set by 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 two sentences, front-loaded with the main purpose, and contains no redundant or extraneous information. Every phrase contributes to understanding the tool's function.

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 core purpose and ranking behavior are clear, but with no output schema, the description does not specify the structure of search results (e.g., whether it returns matches with metadata, default pagination, or how version is interpreted if omitted). This leaves some ambiguity for full invocation, though the essential information for tool selection is present.

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%, providing a baseline of 3. The description enriches the query parameter by explaining match ordering (exact/prefix rank first) and clarifies the version parameter's role as a single-patch scope, adding meaning not present in the schema alone.

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

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

The description clearly states a specific verb ('Search'), a resource ('API names and official documentation text'), and a scope ('within one retail patch'). It also distinguishes itself from siblings like lookup_api by focusing on documentation text search and mentioning exact/prefix ranking.

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

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

The phrase 'within one retail patch' implies a scoping constraint, but it does not explicitly state when to use this tool instead of alternatives such as compare_api, diff_versions, or lookup_api. No direct when/when-not guidance is given, only an implied usage context.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds useful context about the patch-scoped filtering and the types of restrictions, but does not disclose additional behavioral traits like pagination defaults or version handling. This is consistent with the baseline for tools with good 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 a single, front-loaded sentence that communicates the core purpose and scope without any filler or redundancy. Every word contributes to understanding the tool's function.

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 search tool with strong annotations and fully described parameters, the description is sufficient. It clearly explains the purpose and scope, though it does not elaborate on output format or edge-case behavior. Given no output schema and a simple parameter set, this is adequately 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 schema already provides descriptions for all three parameters (limit, query, version), achieving 100% coverage. The description adds minimal parameter-related meaning beyond the patch scoping implied by 'one retail patch'. It does not elaborate on limit or query semantics, so it stays at the baseline.

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

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

The description clearly states the tool finds APIs carrying specific restriction types (combat, secret-value, taint, secure-code, unit-aura) within a retail patch. The verb 'Find' plus the resource 'APIs carrying restrictions' is specific and distinguishes it from the sibling search_api and lookup_api 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 provides clear context for when to use this tool (when searching for restricted APIs in a patch) but does not explicitly mention alternatives or exclusion criteria. It implies usage without naming other tools, so it earns a 4 rather than a 5.

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