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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds substantial behavioral detail: it specifies one GET per document, a 6-second timeout each, and explains the verdict categories (served, missing, gated, soft-404, invalid JSON) and what a client does with each document. The RFC 9728 insertion-form nuance is also disclosed, going well 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?

The description is long but dense; every sentence adds necessary information for a complex tool. It front-loads the purpose, then details documents, verdicts, timing, and an example. There is minimal wasted language, though a shorter version could exist if the tool were simpler.

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 complexity, the description covers all essential aspects: the list of documents, the verdict types, the timeout behavior, the path-based insertion form, and an example. There is no output schema, but the description states what results carry (status, verdict, client behavior). An agent has enough context to invoke it correctly without ambiguity.

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 host parameter is already described, but the description adds crucial semantics: it explains the difference between a bare hostname and a full URL, and how a path enables the RFC 9728 insertion-form check. This adds actionable meaning beyond the schema's basic field 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 clearly states the verb (GET), the resource (discovery documents an MCP client reads), and the action (report what each answered). It enumerates specific documents and verdicts, and distinguishes itself from sibling tools through its focus on pre-handshake reconnaissance. The example host input further clarifies usage.

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 when to use it (to inspect what a client reads before handshake) but does not explicitly contrast it with sibling tools like handshake_report or compare when not to use it. The guidance is clear enough for an agent to infer the primary use case, but it lacks explicit exclusions or alternative 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?

Annotations already signal read-only, idempotent, non-destructive behavior. The description goes further by disclosing concrete side effects: exactly five requests, roughly 6 seconds each, no storage of the URL, server-side URL restrictions, and the report's behavior of flagging HTML/5xx failures. 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 dense but front-loaded with the action and outcome. It packs five test cases, expected codes, output reporting, timing, and an example into one paragraph; every listed item is relevant, though the length prevents a perfect conciseness score.

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 burden of explaining return behavior, and it does: HTTP status and error code side by side, plus flagging of HTML/5xx responses. It also covers request count, timing, fixture behavior, and URL constraints. The main gaps are the exact report shape and the ambiguous '{}' invocation hint.

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 the url parameter, including meaning, example, and restrictions, so the description does not need to compensate. However, the 'or {} for the fixture' aside is ambiguous and conflicts somewhat with the required url property, which prevents a higher 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?

The description names a concrete operation: send five deliberately broken JSON-RPC request variants to an MCP endpoint and inspect responses, with expected error codes for each case. This clearly distinguishes it from sibling report-style tools like discovery_report or handshake_report.

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 makes the usage context clear: it is for checking whether an endpoint responds with proper JSON-RPC errors rather than HTML/5xx pages. It does not explicitly state when not to use it or name sibling tools as alternatives, but the intended scenario is strongly 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 readOnly, idempotent, and non-destructive behavior. The description adds substantial context beyond those annotations: it is deterministic, touches no third party, makes no outbound request, returns exactly the real structuredContent (not a mock), and even lists the specific defects wired into the fixture. This is rich, accurate behavioral disclosure with no contradiction.

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 but repetitive. 'Touches no third party' appears three times, and 'no arguments' / 'no URL of yours is fetched' / 'input is canned' are stated multiple times in slightly different forms. The front-loaded opening is strong, but the redundancy prevents a higher score.

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 fully explains what the tool returns, how to call it, its side-effect profile, and its purpose. An agent has everything needed to invoke it correctly and interpret the result as a real structuredContent response.

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 schema coverage is 100%, so the baseline is 4. The description reinforces this by saying 'Takes no arguments' and showing an example call with arguments={}. There is nothing more to add.

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 ('runs'), a resource ('this server's worked example'), and the exact operation (score_card on a built-in fixture). It is immediately distinguishable from sibling tools like score_card or whoami because it emphasizes that it exercises the server's own end-to-end example with a canned fixture.

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 explicitly tells the agent when to use it: 'Use it to see the shape of an answer before you decide what to send.' It gives clear context for why this is useful. It does not explicitly name alternative tools or state when not to use it, but the intended usage is well conveyed.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description goes well beyond these by disclosing that it makes exactly 3 requests, uses a 6-second timeout, sends a user-agent string, repeats the identical request to test idempotency, and probes with an unpublished version to see how the server negotiates. 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 dense and front-loaded with the core action, then expands into relevant detail: request count, timeout, user-agent, idempotency test, and fixture behavior. Every sentence contributes value, but the structure is a long single paragraph that could be made easier to scan with bullets or shorter sentences.

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 burden of explaining return behavior — and it does thoroughly: negotiated vs requested version, capabilities, serverInfo, timing, transport shape, session id, content-type, and idempotency result. It also specifies request count, timeout, user-agent, and how to invoke the built-in fixture, so an agent has enough context to call the tool 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 100%, so the schema already documents url and protocol_version thoroughly. The description adds an example and explains the built-in fixture, but it does not add substantial new semantic detail to the parameters. A slight inconsistency exists between the description's "call with {}" and the schema's required url, but this is more a usage clarion call than parameter semantics.

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 opens with a specific verb+resource: "POST initialize to an MCP endpoint you name and report what came back." It enumerates the exact report contents (negotiated protocol version, capabilities, serverInfo, timing, transport shape, idempotency result), making the tool's function unmistakable and distinguishing it from sibling tools by its handshake-and-idempotency focus.

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 shows a concrete example (url='https://mcp.example.com/mcp') and an alternative built-in fixture call, which implies when to use it. However, it never explicitly contrasts it with sibling tools like discovery_report or error_conformance, nor does it state when not to use this tool. The usage context is clear but exclusions/alternatives are 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?

The description goes well beyond the readOnly/openWorld/idempotent annotations by disclosing that it makes up to 19 requests, each with a 6-second timeout, and is rate-limited per caller and per target host. It also notes the URL is not stored and gives a clear no-request fixture option, which is important behavioral context for an agent deciding whether to invoke it.

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 every sentence earns its place: it explains what runs, what is returned, why it should be used, its cost/latency characteristics, and an invocation example. The content is front-loaded around the core verdict and then expands into necessary operational details.

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 complexity and lack of an output schema, the description is remarkably complete: it names all four checks, explains the weighted scoring, describes the verdict components, warns about request volume and rate limits, and provides an example URL plus fixture path. An agent has enough context to select and call the tool 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 schema already provides 100% coverage for the url parameter, including its meaning and server-side restrictions. The description adds a practical example and a built-in fixture option, which is helpful, but the "or {}" claim conflicts with the schema's required url field, creating ambiguity for correct invocation.

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 that score_card runs four named checks (handshake_report, tools_list_report, error_conformance, discovery_report) against one endpoint and returns a combined verdict. It distinguishes itself from its sibling report tools by describing the aggregate score, letter grade, and sectioned findings it produces.

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 explicitly identifies the intended use case: "This is the tool to call from a monitor." It explains that the score is stable enough to alert on and findings indicate what to fix. It does not explicitly say when to prefer the individual sibling reports over this aggregate, but the monitoring context and combined-check behavior make the main usage clear.

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, the description discloses concrete behaviors: it makes exactly 3 requests with a 6s timeout each, does not store the URL, and the server refuses its own publisher, IP literals, and private names. It also reveals the fixture mode ('{}') and that each finding names the tool and what breaks.

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 each clause adds operational detail: the handshake→list→validate sequence, the comprehensive checklist of faults, output granularity, request/timeout behavior, and an example. It is a single block of text rather than structured bullets, 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?

With no output schema, the description minimally explains the return as findings that name the tool and the broken rule. It also covers request count, timeouts, server restrictions, and fixture usage. It stops short of specifying exact output format or error behavior, but is largely complete for a read-only linter.

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

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

Schema coverage is 100% and the parameter description is already detailed about what url is and its restrictions. The tool description adds an example URL and introduces the '{}' built-in fixture mode, which goes beyond the schema. The '{}' special case, however, sits awkwardly with the required url 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 clearly states a specific verb ('check'/'Schema-validate') applied to every tool returned by tools/list after a handshake, and enumerates the exact fault categories it detects (missing description, bad inputSchema, JSON-Schema faults, naming collisions, etc.). This scopes it apart from siblings like handshake_report or discovery_report, which target other phases.

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 when to use the tool: to validate the schema quality of all advertised tools on an MCP endpoint, including a fixture example. It does not explicitly contrast itself with sibling report tools, but the workflow is specific enough that an agent can infer it is the linter for tool definitions rather than handshake/discovery.

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, and non-destructive annotations, the description adds meaningful detail: no third-party touch, no fetching, no invented data, and facts sourced only from request headers or a file this host publishes. This materially improves an agent's trust and expectations.

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 front-loaded with the essential safety and determinism facts, then elaborates on what is classified. It is somewhat verbose in the middle, but each sentence adds a distinct behavioral or output-related detail, so little 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?

Without an output schema, the description does a good job enumerating the categories of returned information: user-agent, address, assigned class, prior-visit status, fetch-guard decision, and rate limit. It does not specify exact response keys or data types, so an agent would still need to discover the precise response shape by calling 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?

With zero parameters, the schema alone is nearly empty, but the description explicitly says 'Takes no arguments' and gives the example arguments={}. This fully clarifies the parameter contract and even explains why no arguments exist.

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 purpose: classify the current request and report caller identity, class, rate-limit, and fetch-guard behavior. It clearly distinguishes this from the sibling report/list tools by centering on zero-argument request introspection.

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 clear context for when to call it: it is safe, deterministic, makes no external fetches, and explains the request just sent. It does not explicitly list when to choose an alternative or when not to call it, so it stops short of a 5.

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