PlugMCP directory

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile needs no restating. The description adds value by disclosing the compared facets, but says nothing about behavior on unknown or duplicate slugs, or about how the servers are ordered in the result.

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?

One front-loaded sentence with the action, the input key ('by slug'), and the compared dimensions, with zero filler. The cardinality bound is placed early where it has the most operational value.

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?

An output schema exists and annotations cover the safety profile, so return values need not be described. What remains is the cardinality inconsistency (description says two to five, schema permits one) and unaddressed error behavior for bad slugs, which keeps it from a 5.

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 both parameters are already documented and the baseline applies. The description adds the 'by slug' framing and a 2-to-5 cardinality hint, but that hint conflicts with the schema's minItems=1, which could mislead an agent about whether a single slug is legal.

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 ('Compare ... servers side by side by slug') and enumerates exactly what is compared: trust signals, auth, hosting, transport, tools count, license. That makes the output shape predictable and distinguishes it from single-server siblings like get_server. It stops short of naming a sibling explicitly, so 4 rather than 5.

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 phrase 'side by side' plus 'two to five servers' implies the multi-server comparison scenario, which implicitly routes the agent away from get_server. However there is no explicit when-to-use/when-not statement and no mention of the alternative tools (get_server, search_servers, recommend_servers) for single-lookup or discovery cases.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the return shape varies per client, Grok Bot returns a chat message rather than a config, and the result may include a file path and one-click deeplink.

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 front-loaded sentences with no filler, and the special-case behavior for Grok Bot follows immediately after the general case. The 11-client enumeration duplicates the enum and adds length, but it is not harmful and keeps the description self-contained.

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?

An output schema exists, so return values need not be spelled out, and the description still sketches the response shape. What remains unstated is failure behavior for an unknown slug or unsupported client combination, which is minor for a simple lookup 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?

Schema coverage is 100% and the client enum description already explains grok vs grok-bot and the json fallback, so the description's client list largely restates the schema. The only added nuance is that Grok Bot's value is a chat message, which the schema already notes. 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 the exact resource (the install config or command for one server in one client) and enumerates the supported clients, so an agent can immediately tell this apart from get_server or compare_servers. The enumeration of return content (config file path, deeplink) makes the purpose concrete rather than tautological.

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 phrase 'to install one server in one client' establishes clear usage context: call this when the user needs the actual installation artifact. There is no explicit exclusion or pointer to siblings (e.g., when to use get_server instead of get_install), so it stops short of routing 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is fully covered. The description adds only that the README is trimmed and which fields come back, which is modest extra context rather than new behavioral disclosure.

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, front-loaded with the core purpose and the field list. The enumerated field list partly duplicates the output schema, but the text remains efficient with no 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?

The tool is simple (one required param), an output schema exists to explain return values, and annotations carry the safety profile. Little is missing, though a note on using slugs only from search results and on markdown vs json tradeoffs would make it fully self-sufficient.

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 slug, include_readme and response_format are already documented with defaults and the 8,000-character trim. The description repeats the include_readme trimming but adds no meaning beyond the schema, 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?

States a specific verb and resource ('Details for one server by slug') and enumerates the returned facets (description, tools, auth, transport, health, packages, links). It implicitly distinguishes itself from search_servers by operating on a single slug, though it never names siblings explicitly.

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?

Usage is only implied: an agent can infer it should fetch a slug obtained from search results, and the schema's slug description hints at this. There is no explicit when-to-use or when-not guidance, no mention of compare_servers, and no advice on when to set include_readme.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real behavioral detail beyond them: exactly which artifacts come back (definition, SKILL.md path, per-client install commands, Grok Bot install message) and that include_body returns trimmed SKILL.md text.

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 tight sentences with the resource and key payload front-loaded and no filler. The client enumeration makes it slightly list-heavy, but each clause conveys a distinct return element rather than padding.

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?

An output schema exists, so return values needn't be spelled out, and the description still sketches them. However, for a tool whose whole value is the returned install artifacts, it omits how response_format changes the result and gives no hint about failure when a slug is unknown.

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 slug, include_body and response_format are already documented, including the 6,000-character trim and the enum. The description restates include_body's effect but adds no semantics beyond the schema and says nothing about response_format, so 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 states a specific verb and resource ('One skill by slug') and enumerates the payload — behavior, SKILL.md location, install commands per client, and Grok Bot chat message. It is clearly distinct from a plural search, but it never names search_skills as the sibling that supplies the slug, leaving that routing link to the schema.

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?

Usage is only implied: an agent infers it should call this once it has a slug, and the schema text ('Skill slug from search_skills') carries the prerequisite. The description itself offers no when-to-use or when-not-to-use statement and no alternative paths.

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, idempotentHint, destructiveHint=false and closed-world access, so safety is fully covered. The description adds that each category carries a listing count, which is a useful output trait beyond the structured hints, but says nothing about whether counts are live or approximate.

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 with zero filler. The data description comes first and the actionable routing hint (slug feeds search_servers) follows immediately.

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?

With zero parameters, rich annotations and an output schema documenting the return shape, the definition covers what an agent needs in order to call the tool and use its result. Only the freshness semantics of the counts are unstated.

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 takes no parameters, so there is nothing for the description to disambiguate; the 100% schema coverage 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 names the resource (directory categories) and adds a distinguishing detail, listing counts, which no sibling provides. It lacks an explicit verb like 'list', but 'Directory categories with listing counts' is unambiguous in context and no sibling overlaps with it.

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 states the downstream purpose: the returned slug is meant to be used as the category filter in search_servers, which implies when to call this tool (before filtering). It does not explicitly say when not to call it or whether results are cacheable, leaving the selection logic partly inferred.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds that results are ranked ('best three', 'why it fits') and include health and install data, which is useful behavioral context. It does not disclose ranking criteria, whether results are cached or fresh, or what happens on an empty match set.

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, no filler, and the return-shape sentence is dense with useful specifics. The ordering is slightly off: the usage instruction precedes the statement of what the tool actually does, so an agent skimming the first clause learns how to call it before learning what it is.

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?

With an output schema present, the description does not need to enumerate return fields exhaustively, and it still gives a compact summary of the payload. Inputs are well covered by the schema plus annotations, so the remaining omission — ranking methodology and no-match behavior — is minor for a read-only recommendation 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?

Schema description coverage is 80%, so the baseline is 3. The description reinforces that the task input should be plain-language intent and that the output includes a client-specific install snippet, which ties the 'client' parameter to a concrete effect. It adds little on the 'limit', 'constraints', or 'response_format' parameters beyond what the enum and property descriptions already say.

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 second sentence states concretely what the tool produces: 'Returns the best three servers, each with why it fits, auth, remote or local, health, and the install snippet for the client.' The opening sentence is phrased as caller instruction ('Describe what the user wants to do in plain words') rather than a verb+resource statement, so the tool's verb is really carried by the title. No differentiation from siblings like search_servers or compare_servers, which is a real gap given seven adjacent 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?

'Describe what the user wants to do in plain words' implicitly signals the natural-language, task-first entry point, which contrasts with keyword-style siblings without naming them. There is no explicit statement of when to prefer this over search_servers or compare_servers, and no guidance on what to do when no server matches.

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/idempotent annotations, it discloses ranking order (exact name, then publisher, then tags/description), that official and verified results are boosted, and that duplicates are merged. It omits key-gating limits and pagination behavior, though the schema's parameter descriptions cover those.

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 tight sentences, front-loaded with what the tool finds before the ranking parenthetical and the next-step call. The ranking clause is dense but each part 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 an 11-parameter search tool with a full schema and an output schema, the description covers selection, ranking, and the follow-up action without needing to explain return values. Only the multi-step search-then-install loop is left slightly implicit.

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 every parameter already carries its own explanation. The description restates the query dimensions but adds little syntax or format detail beyond the schema, 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?

States a specific verb and resource ('Find MCP servers') plus the three searchable dimensions (product name, publisher, topic). It also implicitly distinguishes itself from get_server/compare_servers by framing the output as 'compact cards' and pointing forward to get_install.

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 a clear workflow cue: search here, then 'call get_install next'. It does not explicitly contrast with recommend_servers or list_categories, which are the nearest siblings an agent might pick instead, so the alternatives guidance is incomplete rather than absent.

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, idempotentHint, non-destructive, and closed-world, so the safety profile is fully covered by structured data and the description doesn't contradict it. What the description adds is only resource context (which client ecosystems the packs target). It says nothing about pagination flow, result ordering, or rate limits, so it goes no further than the annotations on behavior.

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, no filler. The purpose is front-loaded and the follow-up routing is placed second, which is the right order. Every clause 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 is a simple read-only search with an output schema, full parameter documentation, and complete annotations, so the description does not need to explain return values or paging mechanics. It is nearly complete; only a brief note on pagination or result ordering would make it airtight.

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 schema already documents limit, query, cursor, category, and response_format in detail, including the empty-query behavior and the default of 8. The description's 'by name, publisher or topic' loosely restates the query semantics but adds no syntax, format, or paging guidance beyond the schema. Baseline 3 applies when the schema carries the load.

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 gives a specific verb ('Find') plus the resource ('agent skills') and names the search dimensions: name, publisher, or topic. It even scopes the resource to SKILL.md packs for specific clients. It does not differentiate itself from other search/list siblings such as search_servers, list_categories, or whats_new, so it falls short of a 5.

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 gives explicit routing for the natural follow-up: 'Call get_skill for the install command.' That is a real alternative, but the description gives no when-not guidance and does not say when to prefer this over list_categories or search_servers, so it is clear context without exclusions rather than full when/when-not coverage.

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 cover the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add context — and it does: it discloses result ordering ('best first'), that the payload mixes new servers with health changes, and the default time window. It omits pagination flow and any note on how 'health changes' are represented, which keeps it below a 5.

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 with the core behavior first and the default window second. Nothing is padded and no sentence merely restates the title.

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?

All six parameters are fully documented in the schema, an output schema exists so return shape need not be described, and the description supplies ordering and the default window. The remaining gap is guidance on paging through results and on how the 'health changes' portion interleaves with new servers, but for a zero-required-param read tool this is close to 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?

Schema coverage is 100%, so the baseline is 3; the description earns a bump because 'Defaults to the last 7 days' restates the operative default of `since` in the description body, and 'best first' explains the ordering that no parameter exposes. It adds no meaning for limit, cursor, category, remote_only, or response_format beyond 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 states a concrete resource and scope: servers 'added to the directory recently', ordered 'best first', plus 'health changes'. That is far more specific than the name alone. It does not, however, distinguish this from siblings like search_servers or recommend_servers, so an agent must infer whether 'recently added' overlaps with a filtered 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 'Defaults to the last 7 days' line implies the tool is for recent-arrival discovery, and the schema's `since` cap of 90 days bounds it further. There is no explicit when-to-use versus search_servers/recommend_servers, and no statement of when this tool is the wrong choice.

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