MCP Endpoint Lint - handshake, tool schemas, JSON-RPC errors

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

The annotations already declare readOnly, idempotent, and non-destructive behavior, and the description adds material behavioral detail: exactly one GET per document, "6 s each", and a result vocabulary containing served, missing, gated, soft-404, and invalid JSON. It also explains what a client does with each discovered document, which is valuable context beyond 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?

Most of the description is information-dense and relevant, particularly the endpoint list and per-result explanation. The opening "FIRST CALL, needs nothing: {"name":"whoami","arguments":{}}" is confusing and is not an example of this tool's actual call signature. The long first sentence is somewhat unwieldy but still readable.

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 compensates by summarizing the per-document result fields, the verdict categories, and the behavior a client would take with each document. It also covers host format choices, the built-in fixture, and request count/timing, which is enough for an agent to invoke it correctly. The main unresolved gap is the required-host inconsistency introduced by the "or {}" mention.

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 schema already fully documents `host`, and the description adds useful meaning with the full-URL example and the path-triggered RFC 9728 insertion-form check. However, the "or {} for the built-in fixture" clause conflicts with the schema's `required: ["host"]`, so the agent cannot be fully certain whether `host` is mandatory or optional.

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 the verb and resource precisely: "GET the documents an MCP client reads BEFORE the handshake and report what each one answered" and enumerates the exact well-known endpoints. This clearly distinguishes the tool from handshake_report by positioning it as the pre-handshake discovery step. The confusing whoami prefix does not obscure the core purpose.

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?

"FIRST CALL, needs nothing" gives a clear invocation order and tells the agent no prerequisite setup is required. The host/path example also tells the agent when to use the RFC 9728 insertion-form check. It does not explicitly name alternative tools, but the before-handshake framing provides enough contextual 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 mark the operation as read-only, idempotent, and non-destructive, and the description adds useful behavioral detail beyond that: exactly five requests are made with a 6-second timeout each, expected JSON-RPC codes are listed for each case, and HTML pages or 5xx responses are flagged. This gives an agent a strong model of what will happen.

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

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

The description is dense but front-loaded with the call example and then lists the exact test cases. It earns its length by packing expected error codes and timeout behavior into one block, though it is a long run-on sentence and the 'FIRST CALL' whoami preamble adds minor ambiguity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema, the description carries the return-value burden and does so adequately: it states that the tool reports HTTP status and error code side by side and flags HTML/5xx failures. It also covers request count, timeout, expected error codes per case, and example URLs, so an agent can invoke it correctly without further information.

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 url parameter is already documented with storage and server restriction details. The description adds a URL example and fixture behavior, though '{}' is slightly inconsistent with the required url property.

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: it sends five malformed or invalid JSON-RPC requests to an MCP endpoint and checks the responses. It also explains the report format (HTTP status and error code side by side) and the distinctive failure mode it flags, which separates it from sibling report 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?

It gives explicit invocation guidance ('FIRST CALL, needs nothing') and a concrete runnable example with a URL, plus a fixture alternative. It does not name sibling alternatives or state when not to use it, but the context of testing accidental client errors makes the intended use clear enough.

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 mark readOnly, idempotent, and non-destructive, and the description adds substantial context: no third-party contact, deterministic behavior, in-process execution, a fixture input, one real defect wired per check, and that the return value is the exact structuredContent of a real call, not a mock. This goes well beyond the structured 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 description is heavily repetitive, repeating 'no third party is touched' three times and 'worked example' multiple times. It also includes a raw JSON-RPC POST body that is tangential to invoking this MCP tool and could confuse an agent. The core information is buried in a long, redundant block.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters, has an output schema, and carries safety/lifecycle annotations, the description provides more than enough context: purpose, exact input, real output, safety, determinism, and behavioral caveats. Nothing essential is missing for an agent to decide whether and how to call 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?

The tool has zero parameters, and the description explicitly states 'Takes no arguments' and gives the exact argument shape {}. With no parameters to document, the description handles parameter semantics clearly and accurately, though it somewhat redundantly repeats the empty-argument message.

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 clearly states the tool runs this server's worked example end to end, specifically score_card on a built-in fixture, and returns real structuredContent. It is specific about the resource and action, though it does not explicitly name sibling tools or draw a sharp line against score_card for real inputs.

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 explicitly says to use it 'to see the shape of an answer before you decide what to send' and notes it takes no arguments, is safe, and makes no outbound requests. However, it never explicitly states when not to use it or names an alternative tool for real inputs.

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, openWorldHint, and non-destructive, and the description still adds substantial behavioral context: 3 requests with 6 s timeouts each, the exact user-agent string, the deliberate probe with a version nobody publishes, the byte-for-byte second send to test idempotency, and the fixture path that makes no outbound request. Nothing about its network behavior is left to inference. No contradiction with 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?

Dense but front-loaded: the most critical instruction ('FIRST CALL, needs nothing: whoami') comes first, followed by the report contents and behavioral constraints. Every clause carries meaning — request count, timeout, user-agent, fixtures — with no filler. The cost is a single run-on sentence with embedded parentheticals and em-dashes, which is harder to scan than a structured multi-sentence layout.

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 compensates by enumerating the report's contents: negotiated protocol version, capabilities, serverInfo, timing, transport shape, session id, content-type, and the idempotency result. Combined with safety annotations and complete parameter documentation, an agent has enough to call it correctly. Only the exact return format and error/timeout behavior remain unspecified, though timeouts are at least mentioned.

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, but the description adds genuine meaning beyond the schema: it documents that {} selects the built-in fixture even though url is marked required, and it provides a concrete example URL. It also ties protocol_version to the described negotiation-and-downgrade probe, which the schema alone does not convey.

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 an explicit verb and resource: 'POST initialize to an MCP endpoint you name and report what came back,' then enumerates exactly what is tested — protocol negotiation, capabilities, serverInfo, timing, transport shape, and idempotency. The title ('Does the handshake work, and is it idempotent?') reinforces the scope, and the specificity makes confusion with siblings like discovery_report or error_conformance essentially impossible.

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 sequencing context ('FIRST CALL, needs nothing') and an offline invocation mode ('call with {} to run it against the built-in fixture'), which tells an agent how to bootstrap. However, it never names sibling alternatives or states when not to use it — an agent choosing among handshake_report, discovery_report, and error_conformance gets no explicit routing and must infer it from the names.

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 already indicate read-only, open-world, idempotent, and non-destructive behavior, and the description adds valuable operational facts beyond that: up to 19 requests at 6 seconds each, rate limiting per caller and target host, URL non-persistence, URL restrictions, and a fixture mode with no outbound request. These details help an agent predict cost, latency, and failure modes. No contradiction with 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 description is dense and informative, but the opening 'FIRST CALL, needs nothing...' is confusing because it is not clearly about score_card itself. The rest of the paragraph packs scoring weights, output contents, rate limits, and examples into a run-on structure, making it less scannable than it could be.

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 tool with no output schema, the description does a good job explaining what the verdict contains: score, letter grade, findings by severity, and section details. It also covers request volume, timeout, rate limits, URL constraints, and fixture mode. The main gaps are the ambiguous whoami prefix and the contradictory '{}' fixture example.

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 schema already covers the single url parameter at 100%, so the baseline is 3. The description adds helpful context about URL restrictions and gives an example, but it also says 'or {} to score the built-in fixture,' which conflicts with the schema's required url field. This inconsistency reduces trust in the parameter guidance.

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 action: run the four checks against one endpoint and return a single machine-readable verdict. It explicitly names the underlying sibling tools and makes clear this tool aggregates them, so an agent can distinguish score_card from handshake_report, discovery_report, etc. The title reinforces the purpose.

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 an explicit use case: 'This is the tool to call from a monitor,' and explains the score is stable enough to alert on and the findings say what to fix. The sibling tools are named as components, implying the alternative is to call them individually, but it does not explicitly state when not to use this tool or when a single report would be preferable.

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 readOnly/idempotent annotations, the description discloses concrete behavioral traits: it makes 3 requests with 6-second timeouts, performs a handshake and tools/list, checks a detailed list of schema faults, and reports each finding by tool name and issue. No contradiction with 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 description is information-dense and every clause carries useful content, but it is one long paragraph mixing workflow, validation checklist, timeout, and example. It lacks a clear front-loaded summary and would be easier to parse with structured bullets.

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 tool with no output schema, the description covers input examples, the built-in fixture, request behavior, timeouts, the validation checklist, and the general shape of findings. It stops short of specifying the exact success/empty-result response format, but an agent has enough context to invoke and interpret the 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?

The single url parameter already has 100% schema coverage, so the baseline is 3. The description adds a useful real-world example and a built-in fixture option, but the 'or {}' alternative appears to conflict with the schema's required url, which slightly weakens reliability.

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 title and description clearly define the operation: schema-validate every tool returned by the endpoint's tools/list, with an explicit list of fault types. It is distinguishable from siblings like handshake_report or error_conformance because it targets tool schema and definition quality rather than transport or error behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for linting an MCP endpoint's advertised tool schemas and even details workflow steps (handshake, tools/list, 3 requests). However, it never explicitly states when to prefer this tool over a sibling or when not to use it, so an agent must infer selection from the purpose.

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. The description adds meaningful behavior beyond that: 'Safe to call. Deterministic. Touches no third party. Nothing is fetched to build it...' and clarifies that output derives only from the request headers or an already-published file. No contradiction with 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 description is overlong and somewhat redundant: the final 'Example' restates the return values already listed earlier, and the opening JSON-RPC invocation delays the actual purpose. It does contain useful routing and safety details, but every sentence does not earn its place and the structure is not front-loaded.

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 tool with rich annotations, an output schema, and sibling tools, the description is complete. It covers the endpoint, the empty-arguments expectation, safety, determinism, no third-party fetches, the exact output categories, and sibling routing. An agent has enough context to select and invoke 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?

The parameter schema is empty and already fully clear. The description reinforces the zero-argument nature with 'Takes no arguments' and an example using '{}', so it does not need to add more. The zero-parameter 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 clearly identifies whoami as an identity/record-returning tool: it returns the caller's user-agent, host classification, visit history, per-surface status codes, and server-side policy details. It also differentiates from siblings by noting that the five siblings each answer a different single question about the caller with the same empty arguments.

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 includes a sibling-routing sentence that lists alternate tools and paths, and explicitly says 'Only this server answers the last part.' That gives an agent a clear sense of when this tool is appropriate versus its siblings, though it stops short of a crisp 'use when... / do not use when...' rule.

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