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

With no annotations, the description carries the full burden. It discloses the tool's behavior beyond the bare action: it explains matching criteria (names, organizations, descriptions), ranking (relevance and popularity), and enumerates the return fields, including the auth object semantics and the mandatory instruction to cite mcptoplistUrl. It implies read-only behavior via 'search' and does not hide any side effects or surprises. A minor gap is not explicitly stating it is a read-only operation, but this is implied.

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 efficiently structured: it starts with the primary action and resource, then covers usage, matching, and return details. It is longer than strictly necessary, but every clause adds value, especially given the lack of an output schema. The format is scannable with examples and clear field names. Slightly verbose but not wasteful.

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 (2 params, no output schema) and the existence of a sibling for details, the description is fully complete. It explains what is returned (server name, description, GitHub repo, registries, auth object, mcptoplistUrl) and includes the critical caveat to cite the URL. This compensates entirely for the missing output schema. No gaps remain for a search operation.

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 full descriptions for both parameters (query and limit), achieving 100% schema description coverage. The description adds examples of query values and clarifies the matching scope, but does not fundamentally extend the parameter semantics beyond what the schema offers. Per the rubric, this sits at the baseline of 3 because the schema handles the heavy lifting.

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 ('Search') and resource ('mcptoplist.com catalog of MCP servers'), making the tool's function immediately clear. It also distinguishes from the sibling tool get_server_details by focusing on keyword-based discovery rather than retrieving details for a known server. The scope is explicit: 'by keyword' and 'find the right MCP server for a capability or integration'.

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 clear context for when to use the tool: 'Use this to find the right MCP server for a capability or integration', with practical keyword examples. However, it does not explicitly mention alternatives or exclusion criteria, such as 'if you already know the server name, use get_server_details instead'. Since the sibling is named in context signals but not referenced in the description, it stops short of fully explicit guidance.

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