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

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

Annotations already mark readOnly, idempotent, non-destructive, and openWorld; the description adds that it makes one GET per document with a 6-second timeout, reports per-document status and verdict, and checks both root and RFC 9728 §3.1 insertion forms when a path is supplied. This clearly extends beyond the annotations without contradicting them.

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 it front-loads a confusing JSON-RPC snippet for whoami that is not this tool's invocation, wasting space before the actual action is stated. The rest is well organized with documents, verdicts, timing, and examples, but the extraneous prelude and inline JSON block reduce clarity.

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 stating that each result carries status, verdict, and what a client does with the document, plus timing, path behavior, and fixture support. It covers the main invocation and interpretation needs for a one-parameter read-only diagnostic, though it does not specify the exact report aggregation format.

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 host with 100% description coverage, but the tool description adds further meaning: it accepts a hostname, a full endpoint URL where a path enables the insertion-form check, or {} for the built-in fixture. This goes beyond the schema, although the '{}' option slightly conflicts with the schema's required field.

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: GET the discovery documents an MCP client reads before the handshake and report what each answered, listing exact endpoints and verdict categories. It distinguishes from siblings like handshake_report by emphasizing 'BEFORE the handshake' and from tools_list_report/whoami by targeting well-known documents rather than listings or identity.

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 positions the tool as 'FIRST CALL' and gives concrete host examples, but it never explicitly names alternatives or says when not to use it. The 'FIRST CALL, needs nothing' prelude is ambiguous because the embedded JSON-RPC payload is for whoami, not for this tool, weakening the 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?

The description goes well beyond the annotations: it discloses that the tool makes 5 network requests, waits 6 seconds each, reports HTTP status and JSON-RPC error codes side by side, flags HTML/5xx responses where JSON-RPC errors belong, and supports a fixture that fails two checks. This adds meaningful behavioral context beyond readOnlyHint, idempotentHint, and openWorldHint, and does not contradict them.

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 efficient; every sentence carries useful operational information and it is front-loaded with the essential first-call payload. However, the long parenthetical list of five test cases with expected codes makes it a wall of text that could be parsed more easily with separate lines or clearer separation.

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

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

Given the tool's moderate complexity and the absence of an output schema, the description is remarkably complete: it covers inputs, the exact requests sent, expected JSON-RPC error codes, output behavior (HTTP status vs error code), the HTML/5xx failure condition, request count, timeout, and fixture behavior. An agent can confidently invoke and interpret this tool from the description alone.

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 describes the url parameter fully (100% coverage). The description adds extra value with a concrete example URL and the {} fixture alias with expected failure behavior, which helps an agent select the right input without opening the schema. Slightly more detail on URL edge cases exists in the schema, so this is strong but not a 5.

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 a specific verb and resource: it is an error-conformance linter that sends five deliberately malformed JSON-RPC requests to an MCP endpoint and checks the returned HTTP status and JSON-RPC error codes. This makes it distinguishable from siblings like handshake_report or discovery_report, which target different aspects of endpoint 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?

Usage is clearly conveyed: it explains what to send, the expected error codes for each probe, that it makes 5 requests with 6-second timeout each, and how to choose between an external URL and the fixture via {}. It does not explicitly name when to prefer this tool over sibling alternatives, but the operational context is strong enough to avoid confusion.

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?

Beyond the read-only/idempotent annotations, it discloses that it sends 3 requests, each with a 6-second timeout, uses a specific user-agent, probes an unpublished version to test negotiation, repeats the identical initialize byte-for-byte, and can run against an in-process fixture. This gives an agent a realistic picture of the side effects and network behavior.

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

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

The description is long and dense, but the protocol details, timeout, user-agent, and fixture behavior all earn their place for an outbound network tool. The opening 'FIRST CALL, needs nothing' and embedded JSON-RPC are slightly distracting, but the structure is front-loaded with the core action.

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 exactly what will be reported: negotiated version, capabilities, serverInfo, timing, transport shape, and idempotency result. It also covers the fixture mode and the default protocol version, making the tool callable without missing context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both url and protocol_version with defaults and constraints. The description adds a usage example and clarifies the version probing behavior, but it does not need to add much parameter-level meaning.

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: POST initialize to a named MCP endpoint and report the protocol negotiation, capabilities, serverInfo, timing, and transport shape, plus an idempotency retry. This makes the tool's function clear, but it never names or contrasts sibling tools like discovery_report or error_conformance, so differentiation is left to the reader.

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 invocation context: provide an endpoint URL, optionally a protocol_version, and it fires three requests with a 6-second timeout; it also explains the built-in fixture alternative. It does not explicitly say when to choose this over sibling tools, so there are no exclusions but also no routing guidance.

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

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

Annotations already mark it read-only and idempotent; the description goes further by disclosing the operational cost ('Makes up to 19 requests ... 6 s each'), per-caller/per-host rate limiting, the stable-alert property, and the no-outbound fixture behavior. For a tool with no output schema, this behavioral detail is especially valuable.

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 mostly valuable, but the opening JSON-RPC payload for whoami is not about score_card and pushes the actual purpose statement later. It is not a tautology or padded, but it is less front-loaded 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?

Despite no output schema, the description explains return content, scoring weights, request budget, rate limits, fixture behavior, and an example URL. For a complex tool that aggregates four checks, this is a complete picture for an agent deciding 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 schema already covers the single url parameter at 100%, so the baseline is 3. The description adds a concrete URL example and a fixture option, but the 'or {} to score the built-in fixture' suggestion conflicts with the schema's required ['url'], which could cause an agent to construct an invalid call.

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: 'Run handshake_report, tools_list_report, error_conformance and discovery_report against one endpoint and return a single verdict'. It specifies the output (score, letter grade, findings by severity, section details) and therefore clearly differentiates the aggregator from its 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 concrete selection guidance: 'This is the tool to call from a monitor' and positions it as the 'FIRST CALL', while naming the individual reports it replaces. It does not explicitly state when to prefer a sibling report alone, so it stops short of a full when/when-not matrix.

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 establish readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context beyond them: it makes exactly 3 requests with 6 s timeouts each, follows a whoami-then-tools/list-then-validate sequence, reports per-tool named findings, supports a built-in fixture mode, and (in the schema) refuses its own publisher, IP literals, and private names. No contradiction with the annotations exists.

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 nearly every clause earns its place: workflow sequence, the full check list, request count, timeout, output form, and example. It is long and the inline JSON-RPC payload adds reading weight, but for a multi-category linter this level of detail is operationally necessary and the most critical information (workflow) is 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?

Despite having no output schema, the description covers the return value's nature ('Each finding names the tool and says what breaks'), network behavior, input options, URL restrictions, and privacy ('Not stored anywhere'). The main gap is the absence of an exact output JSON structure, and the {} fixture claim vs required-url inconsistency is unresolved; otherwise the definition is thorough for a single-param, read-only tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (the url parameter is already documented), so the baseline is 3. The description adds a concrete example URL, the fixture alternative, and the '{}' shorthand for the built-in fixture. However, the '{}' suggestion conflicts with the schema's required:['url'] and additionalProperties:false, creating an ambiguity about which invocation is actually valid; that actively undermines the added 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 title and description name a specific verb-resource pair: schema-validate every tool an endpoint advertises via tools/list. The description enumerates the exact fault categories checked (empty descriptions, invalid inputSchema, JSON-Schema faults, name rule breaks, collisions), which sharply distinguishes it from siblings like handshake_report, discovery_report, and error_conformance. An agent can tell exactly what this tool produces without inspecting any sibling 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?

The description conveys clear context: it is the tool to run when you need to lint the schema quality of an MCP endpoint's advertised tools, and it spells out the internal workflow (whoami handshake, tools/list, then validation) plus the fixture alternative for testing. However, it never names sibling tools or states explicit when-not-to-use conditions, so an agent must infer routing from the tool's purpose rather than being told.

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 annotations (readOnly, idempotent, non-destrictive), the description adds determinism, no third-party access, no fetching, and the fact that all data come from request headers or an already-published file. It also discloses response details such as status codes, timeout, rate limit, and refused hosts. 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 a dense, run-on block that embeds a JSON-RPC POST example, repeats the returned fields twice, and inlines a full sibling path/name list. For a zero-parameter tool this is over-long and poorly structured, even though the title and opening clause do front-load the core idea.

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?

Despite the verbosity, the description is complete: it explains exactly what the response contains, the data provenance, determinism, safety, and sibling endpoints. With an output schema present and zero parameters, no critical calling information 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 has zero parameters, so the baseline is 4. The description reinforces 'Takes no arguments' and shows arguments={}, while the schema already declares required=[], properties={}, and additionalProperties=false. Nothing further is needed.

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 explicitly names the tool's output: the caller's user-agent, booking class, prior-visit status, per-surface client record with status codes, and the server's URL-handling policy. It also distinguishes itself from siblings by noting they answer one other question each with the same empty arguments, even though the exact sibling mapping is tangled.

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 strong context for safe invocation — 'Takes no arguments. Safe to call. Deterministic. Touches no third party' — and notes that siblings exist with empty arguments. However, it never states which sibling answers which 'other question', so an agent cannot confidently choose this tool over a sibling from the description alone.

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