mcpindex

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

With no annotations, the description carries the full burden. It discloses key behavioral traits: v1 advisory, conformance monitored but not enforced, and verdicts may be UNVERIFIED if not yet probed. This goes beyond the simple 'assess' operation and informs the agent of potential limitations, though it does not explicitly state read-only behavior or return format beyond referencing a sibling.

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 earning its place: purpose, use case, and caveats. It is front-loaded and concise, with no filler. The reference to check_tool_trust is efficient and avoids repeating verdict shapes.

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 one parameter, no output schema, and no annotations, the description is fairly complete. It explains the aggregated nature, the use case, and the advisory/UNVERIFIED limitations. The only minor gap is not detailing the verdict shape itself, but it points to a sibling for that, which is acceptable.

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% (server_id described as 'Server slug to assess'), so the description does not need to add parameter details. The description provides context about what the assessment covers but not new semantics for the parameter itself. Baseline 3 is appropriate given the full schema coverage.

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

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

The description clearly states the tool performs an aggregated pre-flight trust assessment across all tools on an MCP server, using a specific verb ('assess') and resource ('server trust'). It also distinguishes itself from sibling check_tool_trust by noting the same verdict shape but aggregate scope, making the purpose unmistakable.

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 says to use for 'is THIS server worth integrating?' decisions, providing clear when-to-use guidance. It mentions check_tool_trust with 'same verdict shape,' implying a distinction, but does not explicitly state when not to use this tool or when to prefer alternatives like compare_servers. Thus, it has clear context but lacks exclusionary 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?

With no annotations, the description carries the transparency burden. It discloses the v1 limitation that only REVIEW or UNVERIFIED are produced, and clarifies that UNVERIFIED should be treated as human review required. It remains slightly vague about error behavior or access requirements, but the advisory nature is 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?

Three sentences, all information-dense and front-loaded with the core purpose. No filler or repetition; each sentence adds new value (purpose, return shape, limitations, usage 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?

Given no output schema, the description adequately explains the return object (directive, dimensions, freshness) and the v1 limitation. It omits details about what 'dimensions' and 'freshness' mean, but the overall context is sufficient for a simple 2-parameter tool.

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 provides 100% coverage with detailed descriptions for both server_id and tool_name. The tool description does not add parameter-specific meaning beyond what the schema contains, 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?

The description clearly states the tool returns an advisory verdict object for a specific tool on an MCP server, listing the directive values. It also distinguishes itself from the in-path gate and implies a distinct role among sibling tools by being pre-invocation advisory.

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 says this is a pre-invocation advisory screen, indicating when to use it. It also states what it is not (the in-path gate), and instructs agents on how to interpret UNVERIFIED, giving clear action 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?

No annotations are provided, so the description must disclose behavior. It only lists output content (quality scores, install paths, env vars) but fails to state whether the operation is read-only, requires authentication, or has any side effects, leaving an agent without critical safety information.

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 immediately states the tool's purpose and key details, with no filler. It is concise and 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 simple tool with one parameter and no output schema, the description covers the core purpose and the categories of comparison, giving the agent enough context to invoke it. It does not elaborate on data sources or presentation format, but given the simplicity, it is sufficiently complete.

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 fully describes the single required parameter 'slugs' with the context that these are server slugs to compare. The description adds minimal extra meaning beyond reinforcing the 2-5 count, which is already encoded in the schema's minItems/maxItems, so the baseline of 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?

Clearly states it performs side-by-side comparison of 2-5 MCP servers, listing specific comparison dimensions (quality scores, install paths, env vars). This distinguishes it from sibling tools like assess_server (single server) and search_mcp_servers (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 implies usage for comparing multiple servers by specifying a 2-5 range, but it doesn't explicitly state when to use this tool over alternatives or mention exclusions. No reference to sibling tools is made, so guidance is mostly 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?

With no annotations, the description carries full behavioral burden; it does helpfully disclose the return shape ("a JSON block ready to paste into the client config"), which implies the tool only renders text rather than mutating any config file. It says nothing about failure behavior for an invalid slug/client pair, whether the output is version- or OS-specific, or whether any state changes.

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, zero filler, with the purpose stated first and the return contract second. Nothing could be removed without losing 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 two-required-param retrieval tool with no output schema, the description covers what it does and what comes back, which is close to sufficient. Minor gaps: no note that a slug must first be obtained via search_mcp_servers, and no error or unsupported-client 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?

Schema coverage is 100% and the client enum is fully enumerated, so the schema already documents both parameters. The description only echoes "server and client" without adding format, matching, or fallback detail beyond the schema — 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?

States a specific verb and resource ("Get the exact install command") scoped to two explicit inputs (MCP server, client). No sibling tool produces an install command, so it is trivially distinguishable from search/recommend/compare/assess.

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 phrasing "for a given MCP server and client" implies you must already have selected both, and the schema note says slug comes from search or recommend results, but the description never states the sequencing or what to do when the slug is unknown. Usage is implied rather than directed.

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 no annotations provided, the description carries the transparency burden. It discloses the return format (top 3 picks, reasoning, install commands, quality scores) and implies it does not execute actions beyond recommending. It lacks caveats about data sources or edge cases, but for a read-only recommendation tool this is adequate.

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 exactly two sentences with no filler. It front-loads the purpose and output, then adds the usage trigger. 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 one-parameter tool with a fully described schema and no output schema, the description provides enough context: purpose, output contents, and when to use it. It is complete for its simplicity.

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 fully documents the 'task' parameter with an example. The description only restates 'natural-language task' without adding new semantic detail, so it stays at the baseline for 100% schema coverage.

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

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

The description states the tool's exact function: recommend the best MCP servers for a natural-language task, and specifies the concrete output (top 3 ranked picks with reasoning, install commands, and quality scores). This clearly distinguishes it from sibling tools like search_mcp_servers or compare_servers.

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 says 'Use this when the user asks for the right MCP server for a task they want to do,' providing clear and direct usage context. However, it does not mention when not to use it or point to alternatives among sibling 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?

With no annotations, the description carries the duty to disclose behavior. It mentions search type ('keyword + semantic') but does not reveal return format, pagination, ordering, or any limitations/freshness. A search tool's read-only nature is implied, but more transparency would be valuable.

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 short sentences, front-loaded with the core action ('Keyword + semantic search'), and every word contributes purpose or usage guidance. No redundancy or fluff.

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

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

For a simple 3-parameter search tool with no output schema, the description provides sufficient context: what it searches, scope, and when to use it. It does not specify result contents, but that is not critical given the tool's simplicity and sibling names that hint at follow-up actions.

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 each parameter has a description, providing a baseline of 3. The tool description adds minimal semantic value beyond the schema (e.g., 'semantic' implies natural language query and 'category' hints at filtering), but does not systematically enrich parameter understanding.

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 ('search'), resource ('every MCP server'), and scope ('mcpindex indexes'), clearly distinguishing it from sibling tools like assess_server or compare_servers. The mention of 'keyword + semantic' adds further precision.

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 says when to use the tool: 'when the user knows what tool category they want but not which server.' This is clear context, though it does not enumerate alternatives or exclusions. Given sibling tools are clearly different in purpose, this suffices.

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