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

Annotations already cover readOnlyHint and idempotentHint; the description adds value by stating that the command prints help and exits, and that results are exact and version-accurate. No contradictions with annotations.

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

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

Three short sentences with no filler. The invocation and example are front-loaded, the connection to create_service is stated, and the read-only behavior is given last. 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?

For a single-parameter, read-only help tool, the description plus schema fully cover invocation, parameter semantics, and expected output (exact flags). No output schema is required, and nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and already documents the single optional parameter with guidance about top-level help. The description's example reinforces this but adds little semantic meaning beyond the schema, so the baseline of 3 applies.

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

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

Clearly identifies the operation as running `imq [command] --help` and returning version-accurate flags. The example plus 'The flags it lists are the ones create_service accepts' differentiates it from the sibling create_service 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?

Implies the tool is for inspecting accepted flags before running commands like create_service, and explicitly labels itself read-only. It does not state formal when-not-to-use conditions or compare itself to docs/status siblings, but the context is clear.

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

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

Annotations already signal destructive and non-read-only behavior, and the description adds concrete behavioral detail: global npm install, replacement of any existing imq, and permission requirements. This goes beyond the structured annotations without contradicting them, giving the agent practical 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?

Two sentences with no filler. The core action is front-loaded, and the important side effects and permission caveat are included efficiently. Every clause contributes meaning.

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

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

Given the simple one-parameter signature and rich annotations, the description is sufficiently complete for an install operation. It covers the action, replacement behavior, a related status-check tool, and a permission caveat. The only minor gap is no mention of what the tool returns or prints, but that is not critical for an install-only command.

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 describes the only parameter, version, with its default and meaning. The description adds no further parameter detail because it focuses on command behavior. With 100% schema coverage, the baseline of 3 is appropriate; the description does not need to compensate.

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

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

The description states a specific action ('Install @imqueue/cli globally') with the exact npm command and resource. It also references cli_status, which distinguishes this tool from the related check-status sibling. The purpose is unmistakable and unambiguous.

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

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

The description gives clear context for when to use this tool: to install the CLI globally and replace an existing imq installation. It also mentions cli_status as the tool that reports presence, implying an install-vs-check workflow. It does not explicitly enumerate when not to use alternatives, but the context is strong enough for an agent to select correctly.

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, destructiveHint=false, and idempotentHint=true, aligning with the description's 'detect' and 'report' language. The description adds the dependency context but does not mention potential edge cases like network calls or how version is reported when not installed. Still, given the annotations, behavior is transparent and consistent.

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 short sentences, front-loaded with the core purpose. The first sentence states what it does; the second clarifies when it's needed. Every word earns its place, with no fluff or redundant verbiage.

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

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

Given the tool's simplicity (0 params, no output schema), the description provides adequate context about when to use it (for create_service/generate_client) and when not to (scaffold_*). However, it does not explicitly state the return value for the 'not installed' case, which could be relevant but is a minor omission for such a straightforward utility.

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

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

The tool has zero parametersッチ, so the description inherently satisfies parameter semantics (baseline 4). It doesn't need to elaborate on parameter meanings because there are none. The description's focus on the tool's purpose is sufficient.

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: detecting whether the `imq` CLI is installed and reporting its version. It names the exact CLI and package, leaving no ambiguity. The sentence is specific and immediately understandable.

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

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

The description explicitly identifies which sibling tools require this CLI (create_service, generate_client) and which do not (scaffold_service, scaffold_client). This gives an agent concrete, actionable guidance on when to call this tool versus when it's unnecessary, going beyond generic descriptions.

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

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

The description adds meaningful behavior beyond annotations: `init` is interactive and will time out non-interactively, `set` overwrites values, and nested keys use a dot-path. The destructiveHint annotation is consistent with the overwrite semantics described.

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 dense sentences cover all actions, parameter mapping, a behavioral caveat about interactivity, and the required CLI dependency. Every sentence earns its place and the command syntax is front-loaded.

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

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

For a multi-action config tool with no output schema, the description covers invocation, subcommand semantics, required parameters, and the key non-interactive pitfall. It does not describe return output or config file side effects, but those are partially inferable from the CLI nature and the action descriptions.

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%, so the baseline is 3. The description adds value by mapping actions to parameters (`get [option]`, `set option value`), explaining when `value` is required, and giving a concrete dot-path example (`ci.provider`), which is more than the schema descriptions provide.

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

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

The description states a specific command (`imq config <action>`) and enumerates each supported action with its exact behavior: check, get, set, and init. This clearly distinguishes it from sibling tools like cli_status or cli_help by scoping it to configuration management.

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 operational guidance: `init` times out non-interactively, so `set` is the automatable choice, and `get [option]` can list all when no option is given. It does not explicitly contrast config with sibling tools, but within the tool's own command surface it provides clear when-to-use guidance.

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

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

The description goes beyond annotations by detailing the dry-run default, the exact side effects of apply=true (writes files, may init git, configure CI, push), and the prerequisite that the `imq` CLI must be installed. This adds significant behavioral context beyond the generic openWorldHint and destructiveHint flags, and does not contradict any annotation.

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

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

The description is three sentences, front-loaded with the core purpose and critical dry-run behavior, then covers apply effects and prerequisites. Every sentence adds necessary information with no fluff or repetition. It is well-structured and easily scannable.

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 5-parameter tool with no output schema, the description covers the essential operational aspects: dry-run vs. apply, side effects, CLI requirement, and where to find flags. It leaves minor gaps such as handling of existing directories or exact return format, but these are acceptable given the action-oriented nature and the pointer to cli_help.

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%, so all parameters are already documented. The description adds value by explaining that the `flags` parameter uses cli_help for exact values and that they serve to avoid interactive prompts. It also clarifies the default behavior of cwd. This extra context justifies a score above the baseline 3, though it stops short of exhaustive detail on each flag.

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?

Description states a specific verb ('scaffold'), a resource ('@imqueue service'), and the exact mechanism ('via `imq service create`'). It clearly distinguishes from sibling scaffold_service by specifying the CLI-based approach and highlights the dry-run vs. apply behavior, so an agent can tell it apart without inspecting other 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 clearly explains when to use it (to scaffold a service via the CLI) and the key workflow (dry-run by default, apply=true to write). It points to cli_help for flags, giving practical guidance. However, it does not explicitly name alternatives or state when NOT to use this tool (e.g., when a simpler scaffold suffices), leaving that to inference from 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 flag destructiveHint=true; the description adds value by specifying exactly which actions are destructive (start, stop, restart) and which are not (status), plus the CLI requirement. This goes beyond the annotation's binary flag and helps the agent make safe choices.

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, both essential. The first states the command and resource; the second clarifies the behavioral difference between actions and the prerequisite. No filler, and the key distinction (safe vs. mutating) is front-loaded.

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

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

Given the 7-parameter schema with full coverage and no output schema, the description is adequate. It covers the core behavior and safety profile. It does not explain return values or error cases, but for a process-control wrapper this is a minor gap. The annotations and schema carry the remaining weight.

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%, so the baseline is 3. The description provides no parameter-specific detail beyond the schema; it only gives the overarching command pattern. It does not clarify cwd, calm, path, services, or update semantics, but the schema already documents each.

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

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

The description states the specific verb 'run' with the resource 'a directory of service repositories' and clarifies the actions (status, start, stop, restart). It clearly distinguishes the tool's scope from siblings like cli_status or package_status by focusing on fleet-level control, and explicitly separates the safe `status` action from mutating ones.

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 gives clear context: runs `imq ctl <action>` over a directory, and explicitly contrasts `status` (changes nothing) with mutating actions. It notes the dependency on the `imq` CLI. However, it does not name alternative tools or state when not to use this tool, though the context implies fleet-level control vs. single-service tools.

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

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

The description adds the behavioral requirement that the service must be live and that the CLI inspects it, which is beyond what annotations convey. It confirms a write operation (emitting files) consistent with readOnlyHint=false and idempotentHint=true, with 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?

Two sentences with no redundant text. The command is front-loaded, and the second sentence adds critical prerequisites (live service and CLI requirement) without filler. Every clause earns its place.

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

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

With no output schema, the description is not required to describe return values. It covers the command, output behavior, and prerequisites. The annotations clarify idempotency and non-destructiveness, so the essential context for successful invocation is present, though error handling is not mentioned.

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% for all three parameters, so the baseline is 3. The description mentions the output directory and the service placeholder but does not add details beyond the schema descriptions; it merely echoes the command structure, providing no extra parameter meaning.

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

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

The description states a clear action: run a specific CLI command to emit a fully-typed client into an output directory. It distinguishes itself from a scaffold by emphasizing 'real, fully-typed' and specifies the exact command, so an agent knows exactly what this tool does.

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 provides a clear prerequisite: the target service must be RUNNING because the CLI introspects the live service over its message queue. It does not explicitly name alternatives like scaffold_client, but the prerequisite and the term 'real, fully-typed' imply when this is the right choice over a scaffold.

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, non-destructive behavior. The description adds valuable behavioral details: truncation of large pages (with reporting), refusal of non-imqueue URLs, and how fragments affect the returned content. This goes beyond the annotations without contradicting them.

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

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

The description is four sentences, each adding meaningful information: purpose, fragment behavior, domain restriction, and truncation. It is front-loaded with the primary action and avoids redundancy, making it efficient and easy to process.

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 a single well-documented parameter and annotations covering safety, the description covers everything needed: how to get sections vs. whole pages, allowed domains, and truncation reporting. An output schema exists, so return details are handled separately; no gaps remain for correct invocation.

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

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

The schema covers the url parameter with a description and example (100% coverage). The tool description adds extra semantics: how fragments change the output, explicit domain whitelist, and truncation behavior, which enriches understanding of the parameter's usage 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 states a specific action: 'Fetch the markdown of an @imqueue documentation page by its URL'. It also differentiates from siblings by referencing search_docs as the source of URLs and explaining fragment vs. whole-page behavior, distinguishing it clearly from list/search 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 ties usage to search_docs results and describes how to use fragments for sections, which conveys the intended workflow. It does not explicitly contrast with other tools (no obvious alternative exists), but it states constraints like allowed domains and refusal of others, giving clear 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 mark the tool read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavioral context beyond these: data comes from the npm registry via imqueue.org and is authoritative, versions should not be cross-checked on npmjs.com, and GPL-3.0-only with commercial licensing does not impose copyleft obligations for ordinary network services or SaaS. This directly influences an agent's actions, such as whether to issue copyleft warnings.

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

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

The description is front-loaded with the core purpose and usage demand, but it is quite long and includes a lot of detail about package categories, licensing, and npmjs.com behavior. This extended context is generally valuable for an agent, though some details, such as package category lists, could be trimmed or moved to output-documentation without losing essential guidance.

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 zero parameters, an existing output schema, and annotations that already classify this as a safe, idempotent, read-only lookup, the description covers all necessary context: when to call it, how to use its contents, how it differs from sibling tools, and what legal caveats may affect user-facing claims. Nothing critical is missing for correct invocation and inference.

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 input parameters, so the schema already fully covers parameter semantics. The description instead adds useful output-level context by stating exactly what is available per package: version, licence, minimum Node version, one-line summary, and install command. With no parameters, the baseline of 4 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 states exactly what the tool does: it returns the authoritative catalogue of @imqueue packages, including version, licence, minimum Node version, summary, and install command. It explicitly contrasts with search_docs, so the agent understands this is the full list, not a search/fetch 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 gives direct usage guidance: call this BEFORE adding any @imqueue dependency. It names search_docs as an alternative that works only if the package is already suspected to exist, warns about mutually exclusive package pairs, and instructs the agent to read the 'pick' rule. It also tells agents not to consult npmjs.com because its snippets are stale.

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

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

With destructiveHint=true present, the description adds meaningful context beyond annotations: dump 'never follows/streams, and output is capped', and clean 'deletes the collected log files', precisely scoping what is destroyed. It also discloses the `imq` CLI prerequisite. No statement contradicts 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 tight sentences proceed from purpose to each action behavior then the prerequisite, with the scoping detail ('exits', 'capped') front-loaded into the first sentence. Nothing is redundant or off-topic.

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 moderate complexity (4 optional params, no output schema, no nested objects), the description covers actions well but leaves gaps: it doesn't describe the dump return format, what the cap threshold is, or clean's success/response behavior. An agent calling this would still have reasonable uncertainty about what the output will look like.

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?

Despite 100% schema coverage, the description enriches the action semantics beyond the bare enum: it clarifies dump exits, is non-streaming, and caps output, and that clean removes log files. This is genuinely value-add at the description level rather than mere repetition of 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?

Lead sentence 'Work with logs of services started by `imq ctl`' states a specific verb-resource pair, and the action enum (dump/clean) names the two behaviors. The title and description clearly distinguish it from the fleet-management sibling (`fleet`) and other CLI helpers — no other sibling deals with logs.

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 action semantics (dump returns current combined logs and exits; clean deletes files), which implies when each mode is appropriate. However, it never explicitly names alternatives or conditions for when not to use this tool versus `fleet`, `cli_status`, or `config`.

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 readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context: warns about npmjs bot detection and explains the licenseNote (GPL-3.0-only, NOT AGPL). No contradiction with annotations; this extra detail goes beyond 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 long but front-loaded with the core purpose, then moves to usage guidance, then caveats and parameter details. Each sentence adds context (npmjs warning, license nuance), so it is structured and purposeful, though it could be more concise.

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 single optional parameter and an existing output schema, the description covers all necessary context: when to use, what it returns, caveats about external data sources, and the licenseNote detail. Nothing an agent needs to call it correctly is missing.

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

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

The schema already provides full coverage (100%) for the single `package` parameter, including scope handling. The description repeats the same instruction and adds example package names, but does not introduce new semantic meaning beyond what the schema documents.

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 explicitly states the deliverable: current version, licence, minimum Node version, and last release date for any or all @imqueue packages. It clearly distinguishes itself from external sources like npmjs.com and implies its role relative to siblings like list_packages.

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 a clear trigger ('Ask this whenever you need to state, compare or depend on a version, a licence or a Node requirement') and positions itself as the authoritative answer. However, it does not explicitly name sibling tools as alternatives or state when not to use it, only what it is for.

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 declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds meaningful behavioral context beyond those: it writes nothing to disk, does NOT execute the displayed command, and warns that the generated file's import shape comes from a namespace rather than the obvious default. 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 front-loaded with the critical READ-ONLY caveat and every sentence earns its place: the no-execution warning, the command-generation explanation, the namespace import caveat, and the sibling alternative. It is appropriately sized for the tool's complexity.

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 fully covers what the tool returns, what it does not do, the key import-shape gotcha, and when to choose the sibling tool. An output schema exists, so return-value details are already structured. Nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters and the nested methods structure. The description adds context about the overall purpose but does not provide additional parameter-level meaning beyond what the schema already contains. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: it 'returns text' and 'Explains how to generate and use the fully-typed client' for an @imqueue service, and explicitly contrasts itself with generate_client. An agent can distinguish this tool from its siblings without opening the schema.

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

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

The description gives explicit when-to-use guidance: use this tool when you want the command shown but not run, and 'Use generate_client (local install only) if you want the command actually run.' It also clarifies the read-only nature and names the alternative 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 declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds beyond them: 'writes nothing to disk, creates no project and runs no command', and explains the automatic types.ts generation for non-primitive types with the consequence for client typing. This enriches the safety and side-effect picture well beyond the annotation booleans.

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 content is front-loaded with the critical read-only/side-effect-free behavior, then moves from generated service shape to input usage to type handling to the alternative tool. Each sentence carries unique information, and the structure mirrors the decision process an agent goes through.

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?

Between the annotations, a fully described input schema, the existence of an output schema, and the description, an agent has everything needed to invoke this safely and correctly: side effects are disclosed, the alternative is named, input behavior is explained, and the generated output content is covered. No critical gap remains.

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 gives 100% descriptive coverage for both parameters, so the baseline is 3. The description goes further by explaining that omitting methods yields a starter template and that non-primitive types trigger types.ts generation, which gives the agent contextual meaning not present in the schema field 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 opens by naming the exact output: 'returns generated source code as text' for an 'idiomatic @imqueue/rpc service', identifying the verb and resource. It also differentiates itself from sibling tools by stating it 'writes nothing to disk' and by pointing to create_service as the file-writing alternative, making the boundary unambiguous.

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

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

It explicitly gives the condition for when to switch to a sibling: 'Use create_service (local install only) if you want files actually written.' It also tells the user how to control generation ('Provide the methods you want, or omit them for a starter template'), which is actionable 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 readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds substantial behavioral context: the corpus spans both prose docs and generated API references, each result names its package and carries a URL, and queries may be plain questions or exact symbol names. It also discloses the package-ambiguity behavior and the search-then-read workflow, which no annotation could convey.

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 longer than average (~170 words), but every sentence earns its place: scope, result shape, query modes, purpose, and the list_packages routing caveat. Core function is front-loaded before the caveats, and there is no redundancy with the schema or annotations.

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 100% schema coverage, safety annotations, and an output schema present, the description covers everything an agent needs to invoke this tool correctly: what to search, how to phrase queries, which sibling to use instead in ambiguous package cases, and where results lead next. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains the query parameter's dual mode (plain question vs exact symbol names, with concrete examples like 'RedisQueue.send'), and clarifies the intended use of `package` (search within the package you settled on after list_packages). The `limit` parameter is already fully documented in the schema itself.

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

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

The description states a precise verb ('Search'), names the exact corpus ('official @imqueue docs... and every exported symbol of every @imqueue package'), and defines the output ('most relevant pages with their URLs'). It also distinguishes itself from siblings by explicitly noting that get_doc reads the pages it returns, so an agent can tell them apart immediately.

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

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

It states when to use the tool ('Answers how do I do X in @imqueue' and confirms a signature before code is written) and when not to: for ambiguous queries like 'tracing' or 'database', it directs the agent to 'call list_packages for the choosing rule rather than taking whichever package ranks first' and then pass `package` here. The division of labor with get_doc is also made explicit.

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