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

Annotations already disclose readOnlyHint=false and openWorldHint=true, so the mutating/open nature is covered. The description adds one genuinely useful guarantee beyond that ('Does not silently enable writes'), but says nothing about merge-vs-replace semantics for config, reversibility, or effect on a running capability.

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 action and no filler. The parenthetical is the only slightly wasteful/ambiguous element.

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?

A live-state mutation tool with an open-ended nested config object, no output schema, and zero parameter documentation needs more than two sentences. Nothing explains what a 'capability' is here, what config accepts, or what the caller should expect afterward.

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 0% for two required parameters, and the description adds no meaning for either. The 'config' parameter is a free-form nested object (additionalProperties: true) whose expected keys are undocumented in both the schema and the description, leaving the agent to guess at the shape.

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+resource: 'Reconfigure a live capability'. It gestures at the sibling relationship with '(same path as mcp_update)', which helps separate it from capability_register / capability_unregister, though the parenthetical is cryptic rather than clarifying. Purpose is clear but the line against mcp_update is fuzzy.

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?

No explicit when-to-use, when-not-to-use, or prerequisite guidance. '(same path as mcp_update)' implies overlap with a sibling but does not tell the agent which to pick or under what conditions, so usage must be 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?

The annotations declare readOnlyHint=false and openWorldHint=true, so the detailed safety burden is lower. The description adds real behavioral context: the shared Policy Gateway path, the Safe+readonly+non-blacklist restriction on auto:true, and that suggestions never bulk-register. It still omits what happens on failure, auth/prerequisite needs, or the confirm gate's role.

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?

Brief and front-loaded, leading with the core action before the constraints. The telegraphic phrasing ('Suggest never bulk-registers') is terse but each sentence carries 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 6-parameter, zero-required, mutating tool with nested objects and no output schema or full annotation coverage, the description covers the key constraints but omits return behavior, prerequisites, and details on several parameters, leaving gaps an agent must infer.

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 only 33%, so the bar to compensate is higher; the description names the relevant parameters (suggestion, protocol, name, config) and explains the auto flag constraint, but says nothing about confirm semantics or the shape of suggestion/config objects.

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+resource: 'Hot-add a capability through the shared Policy Gateway', and ties itself to the sibling mcp_add by noting it takes the 'same path'. It's clear what the tool does, though it doesn't distinguish itself from mcp_add's role beyond the shared gateway.

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 usage hints ('Pass a suggestion or protocol/name/config') and a constraint for auto mode, but never says when to choose this tool over the many siblings like mcp_add, capability_configure, or capability_unregister. Usage is implied rather than explicitly scoped.

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 flag destructiveHint=true, and the description goes well beyond them: deletion is immediate and hot, it tears down the adapter instance and all its tools, it bypasses the allowWrite permission gate, and a missing id returns E_NOT_FOUND. These are exactly the operational consequences an agent needs before invoking an irreversible delete.

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?

Four short, dense sentences with the destructive action front-loaded and no filler. Every clause carries distinct information: mechanism, effect, permission model, and failure mode.

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 single-parameter destructive tool with no output schema, the description covers the mechanism, the blast radius, the auth/permission implication, and the failure mode. Nothing an agent needs in order to call it safely is missing.

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?

With one required parameter at 0% schema description coverage, the description should carry the load. It does add error semantics for the id (missing id yields E_NOT_FOUND) and implies the id names a registered capability, but it never states the id's expected form or provenance (e.g., the name returned by capability_register). Partial compensation only.

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+resource ("Hot-delete a live capability") and adds scope details: removes the adapter instance and its tools immediately. It also names the sibling path it mirrors ("same path as mcp_remove"), so an agent can distinguish it from mcp_remove and capability_register without opening any 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?

Gives clear routing context: it is the control-plane path that does not require allowWrite, whereas the Console REST path requires confirm:true. That tells the agent when this variant is the right call. It stops short of an explicit when-not/alternative statement (e.g., use capability_configure for edits), so it is clear but not fully prescriptive.

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 annotation already declares readOnlyHint=true; the description usefully extends this by specifying the read scope ("Scan never opens write/desktop/secrets") and listing what is deferred ("P4 desktop UI deferred"). That adds concrete behavioral context beyond the annotation, though it does not cover the return shape or fallback semantics of the bridge mode.

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?

It is short, but the compression comes at the cost of readability: a wall of terse P0-P4 fragments and mixed-language jargon ("兜底") rather than front-loaded, scannable prose. Density here is under-specification, not conciseness.

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 no output schema and an undocumented parameter, the description needs to carry the burden of explaining what a scan returns and how includeInventory affects it. Instead it only enumerates opaque scan layers, leaving the agent unable to predict results or call it confidently.

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 0% and the single parameter (includeInventory) is never mentioned in the description. The description does not compensate for the coverage gap, so the agent has no guidance on what toggling inventory on/off does.

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 a resource ("Compat Catalog scan") but the verb/behavior is buried under opaque priority jargon: "P0 installed∩catalog + Partner drops", "P1 login clues", "P2 ports". An agent cannot form a clear mental model of what the scan actually produces, and it is not distinguished from siblings like environment_inventory or discovery_scan_host.

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?

There is only an implicit hint that P3 mcpServers is "兜底 only" (fallback only). There is no explicit when-to-use, no when-not-to-use, and no named alternative among the many sibling tools (environment_inventory, discovery_scan_host, capability_register).

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 openWorldHint=true, so the non-destructive, external-network nature is covered. The description adds the important scoping constraint (single host, no ranges), but discloses nothing about rate limits, probing behavior, or what a probe returns.

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 compact sentences with the core action front-loaded and the constraint second; no filler. Slightly terse given it could clarify scope relative to siblings, but nothing is wasted.

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 read-only probe with annotations and no output schema, the description covers the action and scope but omits what a probe yields and when to choose it over sibling discovery tools. Adequate but with clear gaps for an agent selecting among several discovery options.

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 75%, with host, port, and protocols described; only https lacks a description (though its name and default are self-evident). The description echoes the host/port and no-ranges constraint but adds no syntax or format detail beyond the schema, so the baseline 3 holds.

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 'Probe' with the resource 'single host+port' and names what it hunts for (common OpenAPI/SOAP/GraphQL paths). The 'single' scoping implicitly separates it from scan/host-wide siblings like discovery_scan_host, though no sibling is named 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?

The 'CIDR / ranges are never allowed' clause gives a hard constraint for when this tool applies versus a broader scan. However, it never explicitly says when to prefer discovery_probe over discovery_scan_host or discovery_suggest, leaving the routing decision implied.

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 read-only/open-world semantics, and the description adds real operational context beyond them: the allow-scan env var is ignored, timeouts apply, and SSRF protection blocks metadata IPs. This is meaningful governance/security disclosure for a scanning tool.

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 core purpose and the single-host constraint are front-loaded, and the long protocol enumeration is information-dense rather than filler. It reads as compact but slightly list-heavy.

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 no output schema and a complex multi-protocol scan, the description omits what the scan actually returns and roughly how long it takes. The safety constraints are well covered, but the result-shape gap leaves the agent under-informed.

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 only 40%, and three parameters (https, protocols, onlyGivenPort) are undocumented in both schema and description. The protocol list hints at probe targets but never clarifies that 'protocols' filters, what accepted values are, or how onlyGivenPort interacts with the port argument. It fails to compensate for the coverage gap.

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 action (parallel discovery scan) scoped to a single host and enumerates exactly which protocols/services it probes, making the resource and coverage unambiguous. It doesn't explicitly differentiate itself from close siblings like discovery_probe or compat_scan, which keeps it 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 states a hard exclusion (CIDR/ranges never allowed) but offers no positive when-to-use guidance and never names an alternative sibling (e.g., discovery_probe, discovery_suggest). An agent must infer the routing context itself.

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 openWorldHint=true, so safety is covered. The description adds value beyond that by disclosing the output shape (protocol, name, config, confidence) and that results are drafts rather than applied changes — meaningful since there is no output 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?

Two tight sentences with zero filler, front-loaded with the core action before the input hint. It is efficient, though the input hint is compressed to the point of being ambiguous.

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 5-parameter tool with no output schema and no required-parameter guidance, the description leaves three inputs (port, https, protocols) undocumented and never explains how candidates vs. host interplay. It is too thin to fully equip an agent to call this 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?

Schema description coverage is 0% for 5 parameters, so the description must carry parameter meaning. It only touches two inputs ('candidates or a host'); port, https, and protocols are left entirely unexplained in both schema and description.

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 concrete transformation: mapping probe/scan candidates into 'one-click mcp_add drafts' with named fields (protocol, name, config, confidence). This distinguishes it from mcp_add (which applies) and from discovery_probe/discovery_scan_host (which produce raw candidates), though it never names those 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?

'Pass candidates or a host to scan first' implies the precondition that you need prior probe/scan results, and hints at the input mode. But it does not say when to choose this over discovery_probe, discovery_scan_host, or mcp_add_from_discovery, so routing guidance is only implied.

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 openWorldHint=true, so safety is partly covered; the description nonetheless adds real signal: ports are 'best-effort' (results may be incomplete), the snapshot is only a feed, and it will not flip allowWrite. It omits operational traits such as cost/duration of the scan or whether results are cached, which would matter for an open-world probe.

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: the payload is front-loaded in the first, the safety/behavioral constraint in the second. Every clause carries information and none is 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?

With no output schema and no parameters, the description does the heavy lifting by enumerating the returned fields, which is what an agent needs to decide if this snapshot answers its question. It stops short of saying how the snapshot is surfaced to the suggest feed (returned inline vs. persisted), a minor remaining gap.

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 no parameter surface to document and the baseline is 4. Nothing in the description contradicts or obscures the empty input 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 names the artifact precisely (an Environment Plane snapshot) and enumerates exactly what is captured: OS/arch, permission hints, listening ports, runtimes, container clues, config paths. The closing clause ('never auto-registers') implicitly separates it from mcp_add / capability_register / discovery_suggest, so an agent can place it without opening any 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?

It states the trigger mode ('on-demand') and the downstream consumer ('feeds suggest only'), which tells the agent where this fits in a discovery workflow. It also gives hard exclusions (never auto-registers, never sets allowWrite=true), clarifying it is not a substitute for mcp_add. It does not explicitly say when to prefer this over siblings like discovery_probe or discovery_scan_host, so it stops short of a full when/when-not statement.

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 provide only readOnlyHint=false, so the description carries most of the burden, and it does add one genuinely useful behavior: registration is dynamic and tools become available immediately under a protocol.name.operation prefix. It omits durability (persisted or session-only), the allowWrite gating model, and what happens for unsupported protocols or configs, which matters for an additive management operation.

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 action and then the observable consequence. Nothing is padding; the naming pattern is the one detail an agent could not get from the schema.

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 enormous config schema is fully self-documenting and there is no output schema, so return values need no explanation. Still, for a state-changing registration tool with minimal annotations, the description leaves out whether registrations survive restarts, default permission posture for writes, and failure modes for unknown protocols.

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% and the config property already enumerates every protocol's required shape in exhaustive detail, so the schema does the heavy lifting. The description adds no parameter-level meaning beyond that baseline.

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: 'Dynamically register a protocol endpoint', and explains the observable effect (namespaced tools appear as protocol.name.operation). It does not, however, distinguish itself from close siblings like mcp_add_from_discovery or capability_register, which an agent must choose between.

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?

There is no when-to-use guidance and no exclusion of alternatives, despite the sibling list containing mcp_add_from_discovery (adds from discovery), mcp_plan_bridge, and capability_register, all plausible confusions. The agent must infer the selection rule from the names alone.

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 only annotation is readOnlyHint=false, so the description carries the burden of disclosing write behavior. It says 'Register' but does not say whether this persists an adapter, overwrites an existing registration of the same name, validates the payload, or is idempotent — critical for a mutation tool with no other behavioral 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?

A single front-loaded sentence with no filler; the trigger (discovery_suggest payload) leads and the payload fields follow. It is tight but verges on under-specification rather than true concision.

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 four-parameter, nested-object mutation with 0% schema coverage and no output schema, the description is too thin: it never explains the 'suggestion' object, how top-level fields relate to it, whether parameters are required, or what is returned on success.

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 0% and all four parameters (name, config, protocol, suggestion) are undocumented. The description names protocol/name/config, but its fourth item ('confidence') does not correspond to any top-level parameter and the required 'suggestion' object is never mentioned, so it only partially compensates and introduces ambiguity.

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 ('Register') plus the resource ('an adapter') and the source of its input ('a discovery_suggest payload'), which separates it from the sibling mcp_add (manual registration). A reader can tell what it does without opening the schema, though 'adapter' vs 'server' and the relationship to mcp_add remain implicit.

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: the mention of a discovery_suggest payload suggests this should be called after discovery_suggest produces a suggestion. There is no explicit when-to-use, no precondition (e.g., must the suggestion be freshly probed?), and no statement of when to prefer mcp_add instead.

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 readOnlyHint=false the annotation already signals a write, and the description adds real behavioral context: it names exactly what gets blocked (mcp_add, discovery register, invoke) and notes that blacklisting 'still applies in Full mode', which is non-obvious policy detail. It omits reversibility and auth requirements, but disclosure is well 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?

Front-loaded with the verb and resource, then the three modes follow in compact clauses. It is dense but nearly every clause carries distinct meaning; minor redundancy in restating that each mode both hides and blocks.

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 8-parameter mutation tool with no output schema, the description covers the essential semantics (mode selection and pattern syntax) needed to invoke it correctly. It stops short of covering the reason field or any return/confirmation behavior, but annotations already carry the safety profile.

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 only 38%, so the description must compensate, and it does: it maps host+port/url to target, adapterId (protocol:name) to capability, and pattern to tool, plus it documents glob syntax (* = one segment, ** = any) not present in the schema. Only the reason parameter is left unexplained, keeping it just shy of full 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?

States a specific verb (Add) and resource (blacklist entry), then enumerates the three operational modes (target, capability, tool) with their distinct targets. An agent can distinguish this from siblings like mcp_blacklist_remove or mcp_remove purely from the description.

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 effectively routes within the tool by explaining what each kind does (kind=target for protocol+host/port or url, kind=capability for adapterId, kind=tool for glob patterns), which tells the agent when to pick each mode. It lacks explicit guidance on when to use this tool versus alternatives like mcp_remove, so no exclusions are stated.

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, so the safety profile is covered by structured data. The description adds genuine domain context — the canonical match key (protocol + host + port, or normalized url) — which explains how entries are identified. It still omits pagination/result-size behavior, so it is not fully transparent despite the lower annotated bar.

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 purpose front-loaded and no filler. The trailing 'See docs/BLACKLIST.md' is a small dependency on external docs rather than self-contained information, which keeps it from being exceptional.

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 tool with readOnlyHint already given, the definition is close to sufficient. With no output schema, though, it does not describe the returned entry shape (fields, ordering, pagination), leaving an agent to guess what comes back.

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 zero parameters, so the baseline is 4; nothing in the schema needs compensating for. The mention of the match key adds interpretation value even though there is no parameter to describe.

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: 'List operator blacklist entries.' This clearly separates it from the sibling write operations mcp_blacklist_add and mcp_blacklist_remove, though it never names them 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 implied by the verb 'List' — an agent knows to call it to inspect the blacklist. However, there is no explicit when-to-use guidance, no mention of alternatives (e.g. mcp_query_by_protocol for filtered lookups), and no exclusions or prerequisites.

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 only supply readOnlyHint=false, leaving the description to disclose behavior. It does not say whether removal is reversible, what happens when the id does not exist, or whether confirmation/permissions are required — significant gaps for a mutation tool.

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?

A single dense sentence with the action front-loaded and the id-format details parenthetically attached. No wasted words, though the cryptic delimiter notation slightly hurts readability.

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 destructive management operation with only one annotation and no output schema, the description should at least state consequences or side effects of removal. It communicates the target identifier but not the outcome, so an agent cannot fully reason about the call.

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 0%, so the description must carry parameter meaning. It usefully enumerates the accepted id formats (protocol|host|port, cap|<adapterId>, tool|<pattern>), which is genuine added value, but it remains terse and leaves the exact syntax of the pipe-separated forms ambiguous.

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 (Remove) plus resource (blacklist entry) and the identifier it operates on. It clearly distinguishes itself from mcp_blacklist_add and mcp_blacklist_list by naming the removal action, though it does not explicitly name those siblings.

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?

There is no guidance on when to remove an entry versus listing or adding one, nor any prerequisites (e.g., needing to know the exact id first). Usage is only implied by the verb itself.

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?

readOnlyHint=true already tells the agent this is a safe non-mutating operation, lowering the disclosure bar. The description adds the useful detail that the output covers adapter, protocol, local operation, and input schema, but says nothing about error behavior when the name is unknown or the tool is unregistered.

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?

A single front-loaded fragment that wastes no words. It is terse to the point of being a colon-list rather than a sentence, but every token carries 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?

There is no output schema, so the description doing double duty by enumerating the explained facets is valuable. For a single-read-only-parameter introspection tool this is nearly sufficient; a note on failure mode for unknown names is the only notable gap.

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% and the schema already provides a format example ('openapi.widgets.getWidget'). The description contributes nothing beyond what the schema states, 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 (Explain) and a specific resource (a namespaced MCP tool), and enumerates the facets returned: adapter, protocol, local operation, input schema. This distinguishes it from enumerating siblings like mcp_list, though it never names an alternative 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as mcp_list or mcp_query_by_protocol. The agent must infer that this is a follow-up to enumeration purely from the tool name and the 'namespaced' qualifier.

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?

readOnlyHint=true already establishes this is a safe non-mutating read. The description adds some value by naming the returned sub-fields (live/restore_failed, tool counts), but says nothing about freshness, cost, or what 'restore_failed' implies operationally.

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?

A single tight sentence front-loads the resource and lists the salient outputs. No filler, though the parenthetical is slightly cryptic out of context.

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 read-only health check with annotations covering safety, this is nearly adequate, but with no output schema the description only partially characterizes the return payload and never explains the verbose parameter, leaving gaps.

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 0% and the single parameter 'verbose' is never mentioned in the description. Since this is a 1-param tool whose only knob controls output detail, the description should have explained what verbose toggles, but it does not.

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 resource (process + adapter health) and the key outputs (live/restore_failed, tool counts), making it distinguishable from management siblings like mcp_list or mcp_query_by_protocol. It is clear what the tool reports, though the phrasing 'snapshot for agents' is slightly internal-facing.

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 gives no when-to-use guidance, prerequisites, or alternatives among the many sibling tools. An agent can infer it is a diagnostics call, but nothing tells it when this is preferable to environment_inventory or compat_scan.

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 readOnlyHint annotation already establishes this as a safe read, so the description's job is limited. It usefully discloses the defaulting behavior and the layer partition, but says nothing about return shape, result size, or how verbose alters output. Some added context, but not rich.

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?

A single compact sentence with the core purpose and the default-rationale front-loaded; no filler. Every clause carries 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?

With no output schema and only a readOnlyHint annotation, the description should carry more of the return-value burden. It covers the layer concept and default adequately but omits what the listing returns and how verbose changes it, leaving a gap for an agent deciding how to consume results.

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, but the description adds semantics beyond the schema by mapping management to mcp_*/discovery_* prefixes and business to protocol.name.op. The verbose parameter is only explained in the schema, not the description.

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 (List) and resource (tools) plus the organizing concept (layer), and it defines the two layer buckets by their naming patterns. It does not name or differentiate against siblings like mcp_query_by_protocol or mcp_health, so sibling routing is left implicit.

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 default (layer=business) and even justifies it ('so agents are not flooded'), which is useful implied guidance on how to call it safely. However, it never says when to prefer this over a sibling query tool or when to use layer=all/management explicitly.

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 declare readOnlyHint=true and openWorldHint=true, so safety is covered structurally. The description adds a genuinely useful behavioral caveat — 'Does not scan by itself' — which is important given the openWorld hint, since an agent might otherwise assume this tool touches the network. It doesn't say whether the plan is persisted or whether prior registry state is required.

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 waste, and the core transformation is front-loaded before the scope caveat. 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?

For a read-only, open-world planning tool with no output schema, the description effectively names the return content (protocols, example configs, next tool calls) and rules out scanning. An agent has enough to invoke it correctly, though guidance on how the plan relates to the sibling execution tools is missing.

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 two well-described params, so the schema does the heavy lifting — baseline 3. The description's 'natural-language goal' echoes the goal param but adds no syntax or format detail, and the optional host param is not addressed at all.

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+resource: it turns a natural-language goal into recommended protocols, example configs, and next tool calls. It also carves out scope against the discovery/scan family with 'Does not scan by itself.' It stops short of naming a specific sibling (e.g., discovery_suggest), which prevents 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?

Usage is implied: it's the planning step that consumes a goal. The 'Does not scan by itself' clause hints that scanning siblings are needed for actual probing, but it never states when to pick this over close siblings like discovery_suggest or discovery_probe. No explicit when/when-not routing.

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 readOnlyHint annotation already declares this is a safe, non-mutating read. The description adds one piece of behavioral context beyond the annotations: the result set is scoped to 'live' adapters and tools rather than all registered entities. It does not explain what 'live' means operationally or how results are shaped.

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?

A single, front-loaded sentence with no filler or redundancy. It is efficient, though it is arguably too terse for a tool whose key parameter is completely undefined.

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?

No output schema exists, so the description is the only source for what the tool returns, and it says nothing about the return shape or pagination. Combined with a fully undocumented required parameter and no differentiation from sibling listing tools, the definition leaves material gaps for an agent trying to call it 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?

Schema description coverage is 0%, so the single 'protocol' parameter has no documented meaning anywhere except the phrase 'by protocol type'. The description does not enumerate accepted protocol values, state whether matching is exact or partial, or indicate case sensitivity, so the agent must guess at the accepted input format.

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 action (filter) and resource (live adapters and tools) qualified by protocol type, so the intent is unambiguous on its own. However it never differentiates itself from sibling listing tools such as mcp_list or mcp_health, leaving the agent to guess which query surface applies.

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?

There is no explicit when-to-use or when-not-to-use guidance. The agent is not told how this differs from mcp_list, nor what condition should route it here rather than to another discovery or listing sibling.

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 destructiveHint=true and readOnlyHint=false, so the bar is lower; the description adds the useful detail that this is a control-plane action needing no allowWrite, and specifies the two effects (adapter disconnected, tools unregistered). It does not state whether the removal is reversible or what happens on an unknown id.

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, primary action front-loaded, parenthetical sibling reference kept tight; no filler or restated boilerplate.

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 destructive tool with no output schema, the description covers the mutation's effects, its safety/authorization context, and its sibling equivalence. The main gap is the absence of any id-format or error-behavior detail, which the schema does not supply either.

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 0% and the single 'id' parameter has no documented format or type constraint in the description; only implicitly is it identifiable as the adapter id from 'disconnect an adapter'. This partially compensates for the coverage gap but adds little concrete syntax or scoping detail.

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+resource pair ('disconnect an adapter and unregister its tools') and immediately relates it to the sibling capability_unregister via a shared Catalog path, letting an agent place it among mcp_add/mcp_update/mcp_remove without opening any 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?

Gives the operational context that selects this tool ('Control-plane: does not require allowWrite') and names capability_unregister as an equivalent path, but does not state when to prefer this over mcp_update or capability_unregister, nor any exclusions.

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?

readOnlyHint=false already signals a mutation, so the bar is lower, but the description does add real behavioral context: the update triggers a reconnect/reload of the registration's tools. It does not say whether config replaces or merges existing settings, nor whether the operation is reversible or disrupts in-flight connections. Adds value beyond annotations without being fully transparent.

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 tight sentence with the action and its side effect front-loaded; no filler. It is arguably too terse for what it omits, but structurally there is no waste.

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 mutation tool with a nested, undocumented config object, no output schema, and a side effect (reconnect/reload), the description omits the details an agent most needs: what a valid config looks like and whether the update overwrites the prior config.

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 50%: id is documented in the schema, but config is an untyped object with additionalProperties=true and no description anywhere. The description only restates 'config' without explaining its shape or, critically, merge-vs-replace semantics, so it fails to compensate for the coverage gap.

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 (Update) and resource (an existing registration's config) and additionally names the resulting side effect (reconnect/reload its tools). It is clearly distinguishable from mcp_add and mcp_remove, though it never names those 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?

The description gives no when-to-use guidance, no prerequisites, and no routing to alternatives (e.g. mcp_remove + mcp_add for a full replacement). Usage is only inferable from the word 'existing'.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the scope that only ingress=partner entries are returned, which is genuinely useful filtering context. It says nothing about return shape, ordering, pagination, or why the extra architectural notes matter, so it adds modest value over 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 first sentence is front-loaded and efficient. The following two sentences ('Agent-facing northbound is still MCP only. Apps do not implement MCP.') are tangential architecture commentary that does not clearly help invoke this tool, adding noise.

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 parameterless list tool with no output schema, the description covers what it lists and the filter scope. The dangling sentences about MCP northbound and apps add confusion without completing the picture of what the caller gets back. Adequate but with clear gaps.

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?

With zero parameters and 100% schema coverage, there is nothing for the description to clarify about inputs. The '(ingress=partner)' note functions as an implicit fixed filter, which is helpful context even if no parameter exists.

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 (list southbound Partner connections) and pins scope via the '(ingress=partner)' qualifier. It clearly names the resource, though it never names a sibling like mcp_list to sharpen the contrast. The trailing sentences about northbound/MCP/apps describe the surrounding architecture rather than this tool's action.

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 contrast between 'southbound Partner connections' and 'northbound MCP' implies this tool covers a different domain than the mcp_* siblings, giving indirect usage context. However, it never states explicitly when to use this versus mcp_list or any alternative. Usage is left to inference.

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=false and openWorldHint=true, so the agent knows this is a mutating, network-reaching operation. The description adds the useful config-mapping behavior (OpenAPI servers[] become config.baseUrl) but says nothing about side effects of import/register, auth requirements, or what gets created — modest added value against the already-declared write profile.

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; the primary format list leads and edge cases (import-first, Connect target) follow. Dense and jargon-heavy, but every clause carries information an agent can act on.

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 7-param mutation tool with a nested config object and no output schema, the description covers format selection well but omits the register default's implications and any return/effect information. Adequate, not 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?

At 71% schema coverage the schema documents most params, but the description still adds real meaning: 'source' accepts URL or file, 'target' is the gRPC host:port for .proto, and 'config' absorbs the servers[] mapping. Only name/register semantics go unaddressed, which keeps it below the top 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?

Presents a specific verb (Import) plus a precise list of resources (OpenAPI, WSDL, proto, GraphQL SDL, AsyncAPI, and import-first formats), which is far more than a restatement of the name. The only gap is that it never distinguishes itself from siblings like mcp_add or mcp_add_from_discovery, so sibling routing is left to inference.

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 conditional handling guidance for import-first formats ('export OpenAPI') and the Connect proto case, which implies when those branches apply. But it offers no explicit when-to-use-this-vs-alternatives statement against the many sibling management/discovery tools.

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