search_servers

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

With no annotations, the description carries full transparency burden. It discloses the catalog source and mentions full-text query and filters, but does not describe return behavior, defaults for sort/limit, or any external API dependencies. The output schema covers return format, so a 3 is appropriate for the limited extra context.

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

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

Two short sentences: the first states the core action and target, the second lists supported filters. No filler, front-loaded, and 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?

The tool has 7 optional parameters and an output schema. The description covers the main purpose and filter categories, while sort/limit are documented in the schema. It is sufficiently complete for invocation, though it could have explicitly noted that it is a query-based alternative to list tools.

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 parameters are fully documented in the input schema. The description adds only a sentence listing filter types but does not enrich meaning for q, sort, or limit 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?

The description uses a specific verb-resource combination ('Search MCP servers in the awesome-mcp.tools catalog') and lists filters, clearly distinguishing it from siblings like get_server and 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 implies usage via the verb 'Search' and filter support, but does not explicitly contrast with sibling list tools (e.g., list_hot, list_trending) or provide when/when-not guidance. Usage is implied rather than explicit.

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