AI Worlds CLI Knowledge

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

Annotations already declare read-only and idempotent behavior, lowering the bar. The description adds valuable behavioral context: it warns against pretending commands/authority models are identical, and discloses output characteristics (separately ranked groups, source dates, canonical links). This goes beyond the structured annotations and helps set expectations.

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 concise sentences with no filler. It front-loads the main purpose, includes scope (three products), a key caveat, and return details, then lists example use cases. Every sentence earns its place.

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

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

Given the tool's moderate complexity (4 params, 1 required, no nested objects) and the presence of an output schema, the description covers purpose, use cases, and key behavioral traits. It could mention that the tool only supports these three products or clarify the 'separately ranked' grouping, but it is sufficiently complete for an agent to select and 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?

Schema description coverage is 0%, so the description must compensate for parameter meaning. It implicitly explains the 'query' parameter as 'the same task' and 'products' by naming the three supported products, but it does not clarify 'language' or 'limit_per_product' beyond their names/defaults. The description adds some semantic value but not enough to fully cover the schema gap, especially for the language parameter.

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: find evidence for the same task across Claude Code, Codex, and Grok Build. It uses a specific verb ('Find evidence'), specifies the resource (cross-product workflows), and differentiates from siblings by emphasizing comparison rather than single-source lookup or configuration 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 provides explicit use cases ('Best for questions such as configuring MCP, repository instructions, approvals, subagents, or headless CI'), making it clear when to choose this tool. It lacks explicit 'when not to use' guidance or named alternatives, but the context and sibling list imply the appropriate alternative for single-command or single-config lookups.

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 read-only and non-destructive, but the description adds crucial behavioral details: the result is a 'bounded public excerpt' and full text is not available, directing users to canonical_url. This goes beyond the structured fields and helps set expectations.

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, each with a distinct purpose: what it does, what it doesn't do, and the alternative for CLI tools. No redundant words.

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

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

The description covers the core function, limitations, and alternatives, and an output schema exists. However, it omits any explanation of the offset and max_characters parameters, which are left undocumented in the schema as well, so a complete understanding requires external knowledge.

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?

Only 1 of 3 parameters (id) has a schema description; offset and max_characters are undocumented. The description does not explain their meaning or usage, leaving a significant gap for correct invocation.

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

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

The description clearly states it 'Read the bounded public excerpt and metadata for one document returned by worlds_search_knowledge.' It names the specific resource type (knowledge document) and distinguishes from CLI tools by noting 'Structured CLI command tools remain complete.'

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 specifies the context: use for documents returned by worlds_search_knowledge, and explicitly says the service 'does not redistribute article full text; follow canonical_url for the complete article,' which serves as a when-not and alternative. It also hints that structured CLI tools are separate, aligning with sibling 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 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, 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?

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. The description adds value by disclosing the return payload ('bounded excerpts, commands when present, canonical links, sources, and freshness metadata') and the balanced retrieval behavior across locales. 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?

Three sentences with no wasted words. The first sentence states the core verb and object, the second explains a key behavioral nuance, and the third covers scope options and return metadata. Front-loaded and structured for skimming.

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 rich annotations, an output schema (indicated by context), and a thorough input schema, the description covers the essential operational aspects: what is searched, scope selection, and return contents. It does not need to explain offsets or limits because those are already defined in the schema. Minor gap: it could mention multilingual filter options, but the schema handles that.

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%, so most parameters already have descriptions. The description enhances the meaning of the 'scope' parameter by detailing what each option (curriculum, editorial-archive, all) contains and by explaining the default balancing policy. It does not repeat schema definitions verbatim, adding nuance to the retrieval semantics.

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: 'Search the multilingual Claude World, GPT World, and Grok World corpus.' This clearly distinguishes it from sibling tools like worlds_search_cli_reference, which target CLI reference material, and worlds_get_document, which retrieves individual documents.

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 actionable scope guidance: 'Request curriculum for provider-specific advanced lessons, editorial-archive for historical releases and older articles, or all only when intentionally searching everything.' It also explains why the default core scope is balanced. It does not explicitly name alternative tools, but the scope options effectively tell the agent when to request different retrieval collections.

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