mcp-liveness

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

Goes well beyond the annotations by disclosing the credential-free handshake, the full outcome taxonomy (usable/needs_credential/charged/unreachable/local_only/not_listed), SSRF guards (private, loopback, link-local, multicast, cloud-metadata refused; redirects re-checked), and a concrete rate limit of 30 URL checks per minute per caller. It also supplies a base rate ('roughly two in five remote registry listings do not answer'), which no structured field conveys.

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 core behavior, then scoped to outcomes, then constraints; no filler sentences. It is longer than typical but each block carries distinct operational information, with only mild redundancy between the outcome list and the parameter notes.

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, the description carries the return burden and does so by enumerating every outcome string and what each implies. Combined with zero required parameters and public-https restrictions, an agent has everything needed to call this and interpret the result.

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 already 100%, so the baseline is 3, but the description adds real semantics: that exactly one of name/url is accepted, that skipCredentialCheck applies to name checks only and changes what the answer can report (one request instead of up to five), and that URL checks never walk the OAuth chain.

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 (makes one handshake) against a specific resource (an MCP server's endpoint) and names the exact protocol calls used (`server/discover`, `initialize`). The 'with no credential' framing implicitly separates it from the credential-oriented sibling mcp_liveness_check_auth, so an agent can route between them.

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 context ('Useful before relying on a server') and the selection rule for the two mutually exclusive parameters (name for registry entries, url for unregistered or differently-named servers). It does not explicitly say when to prefer the sibling tools mcp_liveness_check_apps, _auth, or _drift, so routing against those 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 cover the safety profile (readOnlyHint, openWorldHint, destructiveHint=false), and the description adds genuinely new behavioral context: no credential is needed, no tool is called, the server is opened as a host would, host-verdicts are judged from published pages rather than by running hosts, and there is an explicit limit of '30 a minute per caller'. The rate limit and the read-only method of inspection are exactly the operational facts an agent can't get from 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 core purpose is front-loaded in the first sentence and the usage triggers are grouped cleanly. The middle paragraph enumerating internal probes (tools/list, resources/read, CSP, ui/initialize, directory-review checks) is longer than an agent needs strictly for selection, but it earns some of its length by signalling diagnostic depth.

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, the description takes on return-value explanation and does so fully: fault attribution, the fix, the source with the date read, and the enumerated verdict set (ok, at_risk, broken, no_ui, needs_sign_in, unreachable). Combined with annotations and a fully documented two-parameter schema, nothing an agent needs to call it correctly 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 description coverage is 100%, so both parameters (the exact Streamable HTTP URL and the four-value host enum) are already documented in the schema, including the ui.domain hash note. The description adds little parameter-level meaning beyond restating 'must be public https' and listing the verdict vocabulary; baseline 3 is appropriate when the schema carries the parameter burden.

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?

It names a specific verb and resource ('Checks a remote MCP server's MCP Apps UI (SEP-1865 ui:// resources)') and states exactly what it returns (the first failing render step, fault owner, fix, source). The scope — external, credential-free, no tool invocation — makes it unmistakably the Apps-UI renderer diagnostic rather than the generic liveness, auth, or drift 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?

It supplies concrete trigger phrases ('blank or invisible frame', 'Resource not found: ui://', 'Invalid ui.domain format', 'annotations_required') that map user symptoms to this tool. It does not, however, name the sibling alternatives (e.g. mcp_liveness_check for plain reachability) or state when to prefer them, so routing against the family 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 cover the safety profile (readOnly, openWorld, non-destructive, non-idempotent), and the description goes well beyond them: the exact ordered probe sequence, that it needs no credential or client registration, that no client is actually run (emulation only), the rate limit of 30 checks/minute per caller, and the full verdict vocabulary. That is the kind of operational context annotations cannot carry.

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 front-loaded with purpose and the returned fields, then the probe steps, then usage triggers. Dense but nearly every clause carries information; the step enumeration is somewhat list-like and could be tightened, but nothing is 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?

There is no output schema, so the description carries the return-value burden — and it does: the first failing step, attribution among server/identity_provider/client (with issue URL), the fix, the spec section, and the meaning of each verdict value. Combined with the disclosed rate limit and no-credential/no-client-run constraints, an agent has everything needed to call and interpret it.

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% — both parameters, including the client enum, are fully documented in the schema. The description restates the public-https constraint and the per-caller rate limit but adds no new parameter syntax or formatting guidance, 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?

The description names a specific verb ('Walks a remote MCP server's OAuth sign-in chain from outside') and resource, then enumerates exactly what it returns (first broken step, responsible party, fix, spec section). It is plainly distinguishable from siblings like mcp_liveness_check (reachability) and mcp_liveness_drift (config drift) 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 gives concrete trigger conditions — a connector error such as 'Authorization with the MCP server failed' or 'Dynamic Client Registration not supported', and pre-publish validation of a sign-in-requiring server. It does not, however, explicitly state when NOT to use it or name which sibling to use instead for plain liveness, leaving that routing 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavior beyond them: snapshots hold content hashes not bodies so schemas are not diffed, `detail` returns the release-asset location for both months, and a month without a snapshot errors with the valid months rather than returning a misleading empty diff. This is exactly the kind of edge-case disclosure the annotations cannot carry.

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 core behavior, then layered usage, limitation, and error handling, each paragraph earning its place. The prose is slightly narrative ('still the same server that code was written against') but nothing is redundant.

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 carries the return burden and does so: 'The answer names the changed tools and the kind of change,' plus the fallback path for exact diffs and the error-on-missing-month contract. Nothing an agent needs to invoke this correctly 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 description coverage is 100%, so both `name` and `since` are fully documented in the schema, including the namespaced format and the omitted-`since` default. The description reinforces the month-vs-latest framing but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a precise verb and resource: it reports which tools were added, removed, or had descriptions/schemas changed between a named month and the latest snapshot. It also explicitly separates itself from its sibling ('A liveness check says a server answers today; this says whether it is still the same server that code was written against'), so an agent can route between mcp_liveness_check and this tool without opening a 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?

Provides concrete when-to-use triggers (a server that behaved differently, a prompt/integration that started failing, before trusting a cached description) and contrasts the tool's purpose against the liveness check. The guidance is actionable and leaves nothing 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 readOnly, idempotent, non-destructive and closed-world, and the description reinforces these with 'makes no network request and its answer never changes between calls' — a useful, unambiguous statement for a reference tool. It adds framing beyond the annotations, though it largely restates the idempotent/openWorld hints rather than revealing new behavioral traits.

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, front-loaded with the action and the enumerated outcome list, followed by one short clarifying sentence about its static nature. Every clause earns its place 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?

With no parameters and no output schema, the description carries the full burden and does so: it lists the six possible outcomes and states that meanings and next moves are included, so an agent knows exactly what the return contains. Nothing needed to call or interpret it 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?

The tool takes zero parameters, so the baseline is 4; there is no argument syntax an agent could get wrong. The description correctly spends no words on inputs and instead documents the conceptual content of the response.

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 ('Returns the six outcomes this server can report') and enumerates the exact outcome values, so an agent knows precisely what it will get back. The closing line ('A static reference') distinguishes it from the sibling check/drift tools that perform live network probes.

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?

Positions the tool for 'an agent choosing a server from the registry' and notes it supplies 'the usual next move for each' outcome, which is clear context for interpreting results. It stops short of explicitly saying to call this instead of or alongside mcp_liveness_check, so no hard exclusions or sequencing are given.

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