mcp

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

Beyond the annotations that already declare readOnlyHint and non-destructive behavior, the description adds valuable context: it returns plain markdown for reading/quoting and refuses any non-imqueue.org URLs. This gives the agent a clear expectation of output format and a security boundary, going well beyond the structured 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 concise, with three sentences that each serve a purpose: stating the action, describing the output, and stating a constraint. It is front-loaded with the main verb and resource, and contains no filler or redundant information.

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

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

For a simple tool with a single parameter and strong annotations, the description is complete. It covers the input (URL), the output format (plain markdown), the use case (reading and quoting), and a key behavioral constraint (only imqueue.org URLs). No output schema is present, but the description sufficiently explains what the agent can expect.

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 fully documents the single 'url' parameter with an example, so the description adds minimal new information about the parameter itself. The phrase 'as returned by search_docs' provides useful semantic context about where the URL should come from, but this is more about usage than parameter meaning, warranting a baseline score.

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 the full markdown') and the specific resource ('an @imqueue documentation page by its URL'), which distinguishes it from sibling tools like search_docs that search rather than fetch by URL. The title reinforces the purpose, and the example URL in the schema adds clarity.

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 this tool: after search_docs returns a URL, and it explicitly notes that only imqueue.org URLs are accepted, which serves as a constraint. It does not explicitly list alternatives or when not to use it, but the context is clear enough for an agent to select this over the search tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it is a safe read operation. The description adds that it returns a one-line summary and install command, and notes 'main' packages, implying a curated list. However, it does not disclose any caveats like potential missing packages or version details, so transparency is moderate 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 a single sentence, front-loaded with the action and resource, and contains no unnecessary words. It efficiently conveys what the tool does, what it returns, and why to use it.

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 zero-parameter, read-only listing tool with no output schema, the description fully explains the return value (packages with one-line summary and install command) and the purpose (choosing the right package). With strong annotations covering safety, this description is complete and sufficient for an agent to understand the tool's behavior.

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 schema fully covers all parameters (100% coverage). The description adds no parameter-specific information, but none is needed. The baseline for zero parameters is 4, which is appropriate here.

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: 'Return the main @imqueue packages with a one-line summary and install command.' The verb 'Return' and the resource 'packages' make the action explicit. The purpose is also given: 'so you can pick the right one,' which distinguishes it from sibling tools like get_doc or search_docs.

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: use this tool when you need to identify and choose among @imqueue packages. It does not explicitly mention alternatives or when not to use, but the purpose implies a selecting scenario. Sibling tools exist, but no direct comparison is made, so it falls short of a 5.

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

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

Annotations already mark the tool as read-only and non-destructive. The description adds that it 'returns instructions only — it installs nothing,' which is valuable behavior context, and clarifies that the described tools act on files/services but this tool itself is passive.

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, immediately states purpose, adds necessary context, and ends with a clarifying disclaimer. No superfluous content.

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 zero-parameter, no-output-schema tool that returns static instructions, the description fully covers what it does, why it's needed, and what it doesn't do.

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

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

There are no parameters, so the schema has full coverage. The description provides no param-specific info needed; baseline of 4 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 clearly states the tool 'returns setup instructions' for the @imqueue MCP server, using a specific verb and resource. It also distinguishes from hosted server offerings by mentioning CLI-backed tools, making it distinct from sibling doc/search/scaffold 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 explains when local installation matters (to get CLI-backed tools that cannot be hosted), giving context for when to use this tool. However, it does not explicitly name alternatives or state 'use this instead of hosted server' as a direct instruction.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds a concrete side-effect disclosure: 'Returns text only — it writes no files.' It also states that it returns the generate command plus an illustrative usage snippet, making the output behavior clear.

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: purpose, generation mechanism, and side-effect note. No wasted words; key information 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 tool that returns text only, the description covers the purpose, the command to show, the snippet, and the no-files side effect. It also notes the client comes from a running service, which is useful context. The output is a simple text return, so no output schema is needed.

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%, with both `service` and `methods` fully described in the schema. The description does not add extra parameter semantics beyond this, so the 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 starts with 'Show how to generate and use the fully-typed client for an @imqueue service', which gives a specific verb ('Show') and resource ('fully-typed client'). It distinguishes itself from sibling scaffold_service by clarifying it returns a command and snippet rather than actually scaffolding files.

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 you need the command to generate a typed client—but it does not name alternatives or provide when/when-not guidance. There is no explicit comparison to scaffold_service or other siblings, so the usage context is only implicit.

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 and non-destructive behavior, but the description adds crucial details: returns source text only and writes no files. It also explains the optional methods behavior, going beyond annotation coverage.

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

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

Two well-structured sentences: the first states the core function, the second covers usage options and output behavior. No wasted words, and the most important information 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 tool's moderate complexity (2 params, no output schema), the description fully covers what is generated, how to customize, and what to expect as output. It is complete for an AI agent to invoke correctly.

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

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

The input schema has 100% coverage for both parameters, including nested method fields. The description enriches this by clarifying that omitting methods yields a starter template, adding meaning beyond 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 identifies the tool's purpose: generating an idiomatic @imqueue/rpc service with specific structural details (IMQService subclass, @expose()d methods, JSDoc types) and a bootstrap. This is a specific verb+resource combination that implicitly differentiates from sibling tools like scaffold_client.

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 usage guidance: provide methods or omit them for a starter template. It does not explicitly mention alternatives or when not to use it, but the clear context of generating a service makes usage evident.

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 and non-destructive behavior. The description adds meaningful context: results include package names, full URLs, and that results can be symbol names or plain questions. It also clarifies that get_doc consumes the URLs, but does not mention pagination or limit defaults beyond schema.

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, front-loaded with the core action, and each sentence adds unique value: scope, output format, input examples, and the link to get_doc. There is no redundant or filler content.

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

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

For a search tool with simple parameters and no output schema, the description fully explains what the tool returns, how to format inputs, and how it fits with sibling tools. It gives enough context for an agent to decide when to use it and what to expect.

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%, with both parameters documented. The description enhances the query parameter by providing concrete examples like 'RedisQueue.send' and 'PgPubSub.listen', clarifying it accepts both questions and exact symbol names. The limit parameter is not discussed in the description, but the schema sufficiently covers it.

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 searches @imqueue docs and exported symbols, returning relevant pages with URLs. It distinguishes itself from get_doc by noting that get_doc reads pages in full, making the purpose 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 explains the tool answers 'how do I do X in @imqueue' and confirms signatures before coding, providing clear use cases. It implicitly differentiates from get_doc by mentioning it reads pages fully, but does not explicitly list when not to use alternatives.

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