@imqueue

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

Annotations declare readOnly/idempotent/safe. Description adds specific behaviors: domain whitelist, fragment handling, truncation reporting. No contradiction; adds value 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?

Three sentences, no fluff, front-loaded with purpose, all information is actionable.

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 an output schema exists)Skip return shape, the description covers input constraints, behavior nuances, and edge cases (truncation). Complete for the tool's complexity.

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

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

The only parameter 'url' is described in schema with allowed domains, but the description adds crucial semantic detail: fragment behavior (section vs whole page) and domain restrictions. This goes well beyond the schema description.

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

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

The description clearly states the action: fetch markdown of a doc page, and specifies the resource (imqueue docs). It distinguishes itself from siblings like search_docs by focusing on 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?

Provides explicit usage guidance: URLs come from search_docs, fragment vs whole-page behavior is explained, and domain restrictions are given. This goes beyond mere purpose and helps the agent decide exactly when and how to call it.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description reinforces these by stating it's 'authoritative' and 'a list'. It adds extra behavioral context beyond annotations: it warns that versions come from npm registry via imqueue.org and are authoritative, that npmjs.com is unreliable, and that copyleft implications are NOT AGPL — which is a non-obvious behavioral trait (license disclosure). It also mentions some pairs are mutually exclusive and install both breaks silently — a significant behavioral warning. This is rich transparent disclosure beyond the annotations.

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

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

The description is dense but front-loaded. It opens with the core purpose and usage recommendation, then adds details about coverage, exclusions, and licensing. Every sentence earns its place — the license explanation and mutual-exclusion warning are necessary for correct usage. However, it's somewhat long (over 200 words), but given the complexity (a catalogue tool with critical usage caveats), it's justifiable. The structure is logical: purpose, when, what, warnings, licensing. I'd give a 4 because it's slightly verbose but well-structured.

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

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

For a tool with zero parameters, no input schema, and an output schema (though not detailed here), the description is complete for an agent to decide to call it and interpret the results. It covers the what, when, why, and caveats. It even anticipates common pitfalls (npmjs.com, AGPL misconception). Given the simplicity of the tool (a list retrieval), nothing is missing for correct invocation. With an output schema present, the description doesn't need to explain return format, and it doesn't, but that's fine per the rules.

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 (parameter count 0), and schema description coverage is 100% (since no params, but the description covers everything). The description adds meaning beyond the empty schema by explaining what the function returns and how to interpret the data (mutually exclusive pairs, license info). Since there are no parameters to document, the description fully compensates. On the calibration, 0 params baseline is 4, but the description goes further by explaining data semantics, so a 5 is justified.

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 is unequivocal: 'the complete, authoritative catalogue of documented @imqueue packages'. It names the exact resource (list of @imqueue packages) and the specific attributes reported (version, licence, minimum Node version, one-line summary, install command). It distinguishes itself from siblings by explicitly noting search_docs 'can only find a package you already suspect exists' and that this is 'the list'. The verb 'List' plus resource is precise, no tautology or vagueness.

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: 'Call this BEFORE adding any @imqueue dependency'. It also provides a clear exclusion: search_docs is for finding packages you suspect exist, implying this tool is for the complete enumeration. It even gives a when-not-to-use hint by directing users not to check npmjs.com, which is a negative usage guideline. This is well above the minimum viable.

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 explicitly states 'it installs nothing', clarifying the tool is purely informational and has no side effects. This adds value beyond the annotations, which already indicate safe read-only and non-destructive behavior. It also explains why the tool exists (local tools cannot be hosted).

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 long, front-loaded with the action, and contains no filler. Every clause serves a purpose: what it returns, why it matters, and what it does not do.

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 are no parameters, an existing output schema, and a simple informational purpose, the description is complete. It states the return value ('instructions'), clarifies side effects, and sets expectations without requiring further detail.

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 there is no param schema to document. The description sufficiently explains the single function of the tool without needing parameter-level detail. The baseline of 4 applies appropriately.

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 'Return the setup instructions' for running the full @imqueue MCP server locally, using a specific verb and resource. It also distinguishes from alternative tools by explaining that the local server adds CLI-backed tools that a hosted server cannot offer.

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 this tool is relevant: when a user needs to run the server locally to access project/service acting tools. It does not explicitly name alternatives or exclusions, but the context implies when local setup is necessary versus a hosted server.

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 substantial context beyond that: full package coverage including cli/mcp, the framework-wide Node/Redis/licence reporting, and the critical licenseNote nuance (GPL-3.0-only NOT AGPL, with an explicit instruction to quote it rather than the bare SPDX id).

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?

Though substantial, every sentence earns its place: purpose is front-loaded, the authority rationale justifies the tool's existence, the licenseNote paragraph carries legally important reporting instructions, and the parameter note closes with invocation guidance. There is no fluff or repetition.

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

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

For a single-optional-parameter lookup tool with a full output schema and complete annotations, nothing is missing. The description covers what is returned, when to use it, why it is authoritative, its scope, output-content nuance, and how to invoke it. An agent can select and call it correctly with no further information.

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

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

Schema description coverage is 100% and the schema already documents the 'package' parameter fully, including the with-or-without-scope behavior and omit-for-all semantics. The description's parameter sentence largely restates the schema, adding no meaning beyond confirming optionality. Baseline 3 applies.

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

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

The description names a specific resource ('any published @imqueue package') and the exact data returned (version, licence, minimum Node version, last release date), plus the all-versus-one scope distinction. This is unambiguous and clearly distinct from siblings like list_packages or search_docs, which serve different purposes.

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?

Gives explicit when-to-use guidance: 'Ask this whenever you need to state, compare or depend on a version, a licence or a Node requirement.' It also explains why this tool is the authoritative answer over external sources (npmjs bot detection, stale cached snippets), effectively excluding alternatives without leaving selection to inference.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses key behaviors: 'returns text and writes nothing to disk' and 'does NOT run the command it shows you.' It also reveals non-obvious generated code structure (namespace import), which prepares the agent for the tool's output. No contradictions with annotations.

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

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

The description is three sentences long but densely packed with unique information. It front-loads 'READ-ONLY', then explains the command, the generated-code quirk, and the alternative tool. Every clause earns its place; no fluff 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 moderate complexity and the presence of an output schema, the description fully conveys what the tool returns, its side effects (none), and important caveats (namespace import, local-only alternative). No critical context is missing 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?

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter-specific meaning; it references 'the illustrative usage snippet' shaped by methods, but the schema already states 'Known methods (used to shape the example call).' The parameter semantics are adequately handled 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 clearly states the tool 'scaffolds' an @imqueue client by returning explanatory text, not executing. It distinguishes from siblings by focusing on client generation (vs scaffold_service) and explicitly contrasts with generate_client. The verb+resource is specific 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?

It provides explicit usage context: when you want the command and usage snippet without running it, and explicitly says 'Use generate_client (local install only) if you want the command actually run.' This gives a clear when-to-use and when-not-to-use with a named alternative.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds valuable detail beyond them: it returns source code as text, writes nothing, creates no project, and runs no command. It also discloses the types.ts generation behavior for non-primitive types and the 'any' fallback if omitted, which annotations do not cover.

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 yet information-dense, with the READ-ONLY warning front-loaded. Every sentence contributes: purpose, output format, usage flexibility, type-generation caveat, and alternative tool. 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 complexity and the presence of an output schema, the description covers all essential aspects: what it generates, how to customize, the types.ts side-effect, and the alternative for disk writes. It is complete for an agent to make an informed decision.

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 baseline is 3. The description adds meaningful context: methods can be omitted for a starter template, and explains the optional flag implications (callers must pass non-optional params). It doesn't rehash schema syntax but clarifies usage scenarios, pushing it slightly above baseline.

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

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

The description clearly states it generates an 'idiomatic @imqueue/rpc service' as text output, with a specific verb (scaffold) and resource (service). It distinguishes itself from the sibling tool create_service by noting that this tool writes nothing to disk, and explicitly directs to create_service for actual file writing.

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 explicit when-to-use guidance ('Provide the methods you want, or omit them for a starter template') and when-not-to-use, naming the alternative tool: 'Use create_service (local install only) if you want files actually written.' This is clear context and exclusion.

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 confirm it is read-only, idempotent, and open-world. The description adds practical behavioral context: it returns the most relevant pages, each result names its package, and it can handle both questions and exact symbol names. It also warns about the package ambiguity, which the annotations don't cover, so it goes beyond 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 thorough but somewhat long. It front-loads the core purpose and return characteristics, then provides usage guidance and examples. Some sentences, like the detailed package ambiguity explanation, are valuable but could be tightened, yet it remains organized and every sentence adds essential context.

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 complexity (multiple packages, potential ambiguity) and the rich schema and output schema (providing return details), the description is comprehensive. It covers when to use, how to handle ambiguous queries, parameter usage, and relationship to siblings (get_doc reads URLs). No major gaps for an agent to select and invoke appropriately.

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 parameters are well-documented in the schema. The description adds meaning to the `package` parameter by explaining the context (mutually exclusive packages) and gives examples of `query` values. It reinforces the purpose of each parameter without duplicating schema details.

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

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

The description clearly states the tool's purpose: searching official @imqueue docs and API references for relevant pages with URLs and package names. It distinguishes from siblings by noting it returns URLs that get_doc reads, and by framing it as the discovery step before get_doc and 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?

Explicitly explains when to use it: for answering 'how do I do X' and confirming signatures before writing code. Provides clear direction for ambiguous queries involving mutually exclusive packages (e.g., pg-prisma vs pg-sequelize) and instructs to use list_packages for choosing rules and to pass `package` once decided, effectively differentiating from siblings.

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