AI Worlds CLI Knowledge

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses key behavioral traits: 'uses single-task depth, never ultra or ultracode orchestration, defaults to read-only, and does not launch a CLI or grant permissions.' It also explains the cross-provider candidate behavior, which is valuable context not captured in 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 a tight paragraph of four sentences, front-loaded with the main purpose. Each sentence adds useful context without being verbose. It could be slightly more compact, but overall it is well-structured and efficient.

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

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

Given the tool's advisory nature and the existence of an output schema, the description covers the core selection logic and key constraints (read-only, no launch, no orchestration). It lacks detail on how selection_scope and execution_intent affect results, but these are partially self-explanatory from enums. The description is complete enough for an agent to invoke 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 description does not explain any of the parameter semantics. Schema coverage is only 17%, and the description only indirectly references CLI context ('within the caller's actual CLI set', 'single CLI', 'multiple CLIs') but never defines task, current_cli, available_clis, selection_scope, or execution_intent. The description fails to compensate for the low schema coverage.

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

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

The description uses specific verbs and resources: 'Choose the maximum-depth model-and-effort pairing for one difficult problem within the caller's actual CLI set.' This clearly distinguishes the tool from siblings like worlds_compare_cli_workflows or worlds_plan_cli_work by focusing on selecting the strongest model for a single hard problem.

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 on when to use the tool (for one difficult problem) and exclusions: 'never ultra or ultracode orchestration,' 'does not launch a CLI or grant permissions.' It also explains behavior for single vs. multiple CLIs, but doesn't explicitly name alternative sibling tools or give a formal '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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description goes beyond that by disclosing how results are presented: 'separately ranked groups with source dates and canonical links.' It also states an important behavioral nuance: 'without pretending their commands or authority models are identical,' which is valuable context for users expecting a unified answer. No contradictions.

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

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

Two sentences, front-loaded with the core purpose, then usage examples, then output details. Every clause adds value without padding. The structure is ideal for quick scanning in a tool list.

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 there is an output schema (context signal) and detailed annotations, the description doesn't need to explain return formats or safety. It covers purpose, typical usage, and output grouping. The main gap is the lack of parameter-level detail (see parameter_semantics), but overall the tool is well-understood from the description alone. A complete description would at least hint at the 'products' filter.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It explains the general purpose ('task' implies the query) but never mentions the 'products' array (allowing a subset of Claude Code, Codex, Grok Build), the 'limit_per_product' parameter, or the 'language' parameter. Users cannot infer these options purely from the description; they'd need to inspect the schema, which is the opposite of good compensation.

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

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

The description opens with a specific verb and resource: 'Find evidence for the same task across Claude Code, Codex, and Grok Build.' It clearly distinguishes this compare tool from siblings like worlds_get_cli_workflow (which likely returns a single workflow) and worlds_search_cli_reference (which searches reference material). The added detail of 'separately ranked groups with source dates and canonical links' further pinpoints the tool's unique scope.

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

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

The description gives clear context by listing example use cases: 'configuring MCP, repository instructions, approvals, subagents, or headless CI.' The phrase 'Best for questions such as' signals when to prefer this tool. It doesn't explicitly say 'when not to use' or name alternatives, but the scope is well-implied. Sibling tool names like worlds_get_cli_command indicate a more narrow single-product lookup, but this exclusions aren't stated directly.

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, non-destructive behavior. The description adds useful context beyond that: it specifies what 'captured flags, arguments, value shapes, availability, risk, release metadata, and official source links' are included, and notes the input can be a stable id or full command path. This enriches behavioral understanding without contradicting annotations.

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

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

The description is two sentences with zero fluff. The first sentence is the core functional statement, and the second sentence adds input flexibility. It is front-loaded, concise, and every word contributes.

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 only two simple parameters, comprehensive annotations, and an output schema, the description is quite complete. It covers the tool's purpose, output contents, and input flexibility. The only gap is the absence of explicit usage guidance relative to sibling tools, but this does not significantly hinder understanding for a simple 'get' operation.

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

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

The schema provides no descriptions (0% coverage), but the description adds meaningful semantics for the 'command' parameter by stating it accepts 'a stable id or full command path'. The 'product' parameter is self-explanatory through its enum values. This compensates reasonably well for the missing schema 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 clearly states the tool returns 'one current command path' with detailed contents (flags, arguments, risk, etc.), using a specific verb ('Return') and resource. It distinguishes itself from sibling tools like worlds_get_cli_workflow and worlds_search_cli_reference by focusing on a single command's full metadata.

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 intended use is implied—get a single command's details by id or path—but there is no explicit guidance on when to prefer this over siblings like worlds_search_cli_reference for searching or worlds_get_cli_workflow for workflows. No alternatives or exclusions are mentioned.

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 read-only and idempotent behavior. The description adds valuable context beyond annotations: it explicitly states that the tool returns only public schema metadata and source links, never local values. This is a critical behavioral disclosure that helps an agent avoid surprising side effects or privacy concerns.

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 consists of two concise sentences with no filler. It front-loads the core purpose and adds a relevant behavioral caveat. Every word earns its place, and the structure is entirely appropriate.

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 search tool with annotations and an output schema, the description covers the primary purpose and key safety trait. However, with 6 parameters and zero schema descriptions, the lack of parameter-level detail leaves a notable gap. The description is adequate for a basic agent but not fully complete for complex queries involving filters like 'availability'.

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

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

The input schema has 0% description coverage, so the description must compensate. It provides context for two parameters: 'product' (one CLI) and 'include' (configuration vs environment). However, it does not explain 'query', 'availability', 'limit', or 'offset', leaving several parameters underspecified. The description only partially compensates for the lack of schema 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 clearly states the tool's function with a specific verb ('Search') and resource ('configuration keys and environment-variable names'), plus the scope ('one CLI'). It effectively distinguishes itself from sibling tools like worlds_get_cli_command or worlds_get_cli_workflow by focusing on configuration metadata.

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 finding configuration keys and environment variables but provides no explicit guidance on when to use this tool over alternatives. It does not mention sibling tools or exclude any cases, so guidance remains implicit 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond annotations: the tool returns recorded command steps and does not translate flags between providers. This is consistent with the annotations and no contradiction is present.

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, tightly worded sentence (13 words) that immediately states the action and key differentiator. No filler or redundancy.

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

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

Given the tool's simplicity, the output schema, and annotations, the description adequately covers the core purpose and the distinguishing 'without translating' behavior. It could be slightly more complete by explicitly naming the parameters or mentioning when to use this over get_cli_command, but overall it is sufficient.

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

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

Schema description coverage is 0%. The description does not explain the `product` or `workflow` parameters, only indirectly referencing 'provider-specific'. The schema's enum for product is helpful, but the workflow parameter remains underdescribed. The description should compensate for the lack of schema descriptions but does not.

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 action (find), the resource (one provider-specific workflow), and the specific output (recorded command steps). It distinguishes from siblings like worlds_compare_cli_workflows (compare multiple) and worlds_get_cli_command (single command) by focusing on a full workflow without translation.

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 'without translating flags between providers' provides clear context for when to use this tool: when you need the original provider-specific commands, not a translated version. It does not explicitly name alternatives or exclusions, but the sibling tool list implies the comparison tool is for cross-provider needs.

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, idempotentHint, and non-destructive. The description adds that the excerpt is bounded and public, that the manual is source-checked, and that structured tools are separate, providing context beyond annotations.

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

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

The description is three sentences with each sentence adding unique value: what it does, how to get complete manual, and relationship to structured tools. No fluff.

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

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

With an output schema and rich annotations, the description covers the tool's purpose, relationship to search, and limitations. However, the lack of explanation for offset and max_characters prevents a perfect score.

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

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

Schema description coverage is only 33% with only 'id' described. The description mentions id indirectly via 'returned by worlds_search_knowledge' but does not explain offset or max_characters. The term 'bounded' hints at max_characters but is insufficient for two undocumented 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 uses a specific verb 'Read' and identifies the resource as 'the bounded public excerpt and metadata for one source-checked CLI manual returned by worlds_search_knowledge.' It distinguishes from sibling tools by mentioning the source search and contrasting with structured CLI command 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 explicitly states the tool is for documents returned by worlds_search_knowledge and advises following canonical_url for the complete manual. It also clarifies that structured CLI command tools remain complete, indicating when not to use this tool.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable context by stating this is a public DTO that excludes sensitive data (local paths, packages, private repo URLs). This goes beyond the annotations and clarifies the tool's safety and privacy posture.

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

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

The description is compact and front-loaded, with the first sentence listing the return contents and the second sentence clarifying exclusions. Every sentence adds useful information without padding 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 tool has no parameters and a rich output schema, so the description does not need to explain return values. It covers the tool's scope, what it returns, and what it excludes. Combined with annotations, the description is fully sufficient for an agent to select and invoke this 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 tool has zero parameters and the schema is empty, so there are no parameter semantics to explain. The description does not need to compensate for missing parameter information. The baseline of 4 applies because the parameter space is trivial and fully covered by 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 a specific verb ('Return') and enumerates exactly what is returned: public corpus counts, supported worlds, languages, products, source-quality counts, build commit, and publication gate. This clearly distinguishes it from sibling tools that focus on CLI commands, workflows, and configurations.

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

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

The description implies when to use the tool (to get catalog status and counts) but does not explicitly state when to prefer it over alternatives. The note about deliberately excluding local paths and private URLs provides a hint about what it does not contain, but no explicit alternative tools are mentioned.

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 valuable behavioral context by calling the data 'snapshots' and warning that it may be stale, which is not conveyed by the annotations. It also notes the catalogs are 'source-grounded' and 'dated', further clarifying the nature of the data.

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—two sentences, with the main content front-loaded in the first sentence and a necessary caveat in the second. Every clause adds meaningful information with no redundancy or filler.

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

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

Given the output schema exists, return value details are not required. The description covers the tool's scope (products, features, caveat) sufficiently for a list operation. It could add a bit more context on how to interpret 'source-grounded' or when snapshots are taken, but the provided information is mostly complete for an agent to use 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 sole parameter 'products' has an enum with clear values (claude-code, codex, grok-build) and a default, so its meaning is evident from the schema. The description mentions the three target products but does not explicitly map them to the parameter or explain how the parameter controls the output. Given the parameter's simplicity, this is adequate but not compensatory for the 0% schema description coverage.

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

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

The description uses a specific verb ('Return') and clearly identifies the resource ('dated, source-grounded model catalogs for Claude Code, Codex, and Grok Build'). It lists concrete aspects (selector syntax, effort support, availability constraints, orchestration modes), which distinguishes it from sibling tools like worlds_list_cli_versions.

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 its use for obtaining model catalog snapshots and explicitly advises verifying the live account catalog before launch. However, it does not mention when to prefer this tool over alternatives or state any exclusions, so it falls short of providing explicit usage 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, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds useful context by specifying exactly what data is returned, which goes beyond the annotations. No contradictions or hidden side effects are present.

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 direct and information-dense, listing specific output fields without redundancy. It is appropriately sized and front-loaded with the verb.

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 return content well and aligns with annotations, and an output schema exists for return structure. However, it omits parameter usage and does not differentiate from sibling tools like worlds_list_catalog, leaving some contextual gaps for an agent.

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

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

Schema description coverage is 0%, yet the description does not explain the 'products' parameter or its enum values. It states 'for all three CLIs' without noting that a subset can be requested, which is misleading and leaves the parameter's purpose unexplained.

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 ('Return') and enumerates precise output fields (release snapshot, capture date, entity counts, official sources, website reference, drift status) for all three CLIs. This clearly distinguishes it from sibling tools that handle workflows, commands, configurations, or searches.

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

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

The description implies usage when a caller needs release/coverage metadata, but it does not explicitly mention when to use this tool over alternatives or list exclusions. It also fails to clarify that the optional 'products' parameter can filter to a subset, potentially conflicting with the phrase 'all three CLIs.'

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description goes well beyond that. It adds behavioral details such as 'dependency-aware,' keeping 'CLI fit, orchestration, permissions, handoff context, and verification separate,' and the 'continuity-first' routing policy. It also explicitly states what the tool will not do (claim benchmark superiority, launch another CLI, bypass permissions), which is valuable boundary-setting. No contradiction 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 two dense sentences with no filler. The first sentence front-loads the primary action and scope; the second adds constraints and routing policy. Every clause contributes meaningful detail: read-only, dependency-aware, separation of concerns, continuity-first, and explicit exclusions. This is exemplary conciseness for a tool with 10 parameters.

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

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

Given the tool's complexity (10 params, enums, exact system) and that an output schema exists, the description does a strong job of establishing the tool's purpose, behavioral boundaries, and routing policy. It lacks explicit parameter guidance, but that is partially covered by the schema (even if descriptions are sparse). The mental model it provides is sufficient for an agent to decide when to use it and roughly what inputs to provide, though a little more on how to structure workstreams would push it to a 5.

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

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

Schema description coverage is only 10% (only current_cli has a description), so the description must compensate. It barely touches on parameters: it mentions 'workstream' and 'dated-catalog model' but does not explain the meaning of key parameters like strategy, orchestration_mode, risk_tolerance, workstreams, or available_clis. The agent is left to infer most parameter semantics from enum values and names, which is insufficient for a 10-parameter tool.

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: 'Create a read-only, dependency-aware work plan across Claude Code, Codex, and Grok Build.' This clearly states what the tool does and differentiates it from sibling tools like worlds_get_cli_command or worlds_compare_cli_workflows, which are more about retrieval or comparison. The additional clause about routing and exclusions further cements its unique role as a planning tool.

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 the tool: when planning work across multiple CLIs (Claude Code, Codex, Grok Build). It also states exclusions: 'does not claim benchmark superiority, launch another CLI, or enable permission bypass,' which tells the agent when not to invoke it. However, it does not explicitly name alternative sibling tools for those excluded cases, so it falls short of a full 5.

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

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

Annotations already declare the tool as read-only and idempotent, so the description does not need to restate that. It adds that results contain 'factual metadata and official source links,' which is a useful behavioral detail. However, it does not disclose potential limitations like pagination behavior, response size, or what 'release drift' precisely returns. The description adds some value beyond annotations but not deep context.

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

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

The description is two sentences, front-loaded with the main verb and search target. It covers the scope, products, and result content with no redundant phrases. Every word contributes to understanding the tool's purpose.

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

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

Given the tool's moderate complexity (6 parameters, 0% schema coverage, rich output schema), the description provides a solid high-level overview of what is searched and what results contain. It is complete enough for a search tool with standard parameters, though it could be more detailed about parameter usage and the meaning of 'current' vs historical versions. The output schema likely handles return value transparency.

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

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

Schema description coverage is 0%, so the description must compensate. It does add meaning for the 'kinds' parameter by listing searchable categories (command paths, flags, etc.) and implicitly mentions 'products' via product names. However, it does not explain parameters like limit, offset, or availability, and does not map 'release drift' to the 'drift-note' kind. Partial compensation, but gaps remain.

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: searching current CLI reference data across command paths, flags, interactive commands, configuration names, environment-variable names, workflows, and release drift for specific products. It uses a specific verb ('search') and distinguishes itself from sibling tools like worlds_get_cli_command (which retrieves a specific command) and worlds_search_knowledge (broader knowledge search).

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

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

The description provides clear context about what can be searched (command paths, flags, config keys, etc.) and which products are covered (Claude Code, Codex, Grok Build). It implies usage for finding CLI reference details, but does not explicitly state when to prefer this tool over get/compare/list siblings. No exclusions or alternative tool mentions, but the context is sufficiently clear for basic selection.

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 useful behavioral detail about return contents ('bounded excerpts, commands when present, canonical links, official sources, and review dates'). It also confirms state non-modification, which is redundant but consistent with annotations. No 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?

Three sentences, each earning its place: scope, exclusions, and returns. Information is front-loaded with the core verb and resource. The dense numeric details (162 manuals, 18 modules, three languages) are compact and valuable for quick understanding.

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

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

Given the presence of a rich output schema and annotations, the description need not explain every return value. It covers the corpus scope, exclusions, return content, and state behavior. For a search tool with 9 params and sibling context, this is fully sufficient to guide selection and 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 description coverage is 78%, and the schema already provides meaningful descriptions for most parameters (query, scope, worlds, products, languages, content_types, source_status). The description adds no additional parameter-level semantics, only high-level corpus characteristics. This aligns with the baseline of 3 for high schema coverage.

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

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

The description clearly identifies the verb ('Search') and a specific resource: '162 multilingual, source-checked operating manuals for Claude Code, Codex, and Grok Build'. It also scopes the corpus precisely (18 modules per product, three languages) and explicitly lists exclusions, which helps differentiate from sibling tools like worlds_search_cli_reference or worlds_get_document.

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

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

The description gives clear context for when this tool is appropriate: when seeking operating-manual knowledge for the listed CLI products. It also provides an explicit when-not by stating 'Website articles, news, newsletters, opinion, and release archives are not in this corpus.' However, it does not name any alternative sibling tools or state 'use this instead of X', so it stops short of the highest bar.

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