mcp-server

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

Annotations already cover readOnlyHint=true and openWorldHint=true, so the description's added value is describing the two-phase simulation (OPTIONS preflight plus the actual request) and the shape of the result ('verdict with reasons'). It doesn't mention rate limits or that the server under test is contacted live, which would complete the picture.

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 dense sentence with the core action front-loaded and no filler; every clause (preflight, actual request, returned headers, verdict with reasons) carries distinct 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, the description usefully states what comes back (Access-Control-Allow-* headers and an allowed/blocked verdict with reasons), which is the main thing an agent needs. Minor gaps remain around the method parameter and what a blocked verdict looks like, but the coverage is solid for a 4-parameter diagnostic 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 75% and url, origin, and requestHeaders are already documented in-schema; the description's 'from a given origin' and 'preflight (OPTIONS)' loosely map to the origin and method inputs but add no format or syntax detail. The method enum/default and the custom-header semantics remain explained only by the schema, 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 (simulate/check), the exact resource (browser CORS preflight and actual request) and the output produced (Access-Control-Allow-* headers plus an allowed/blocked verdict). This is easily separable from siblings like check_ssl, scan_security_headers, or trace_redirects.

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 the tool is useful (diagnosing browser cross-origin failures) through 'Simulate a browser CORS preflight', but never states prerequisites, when to prefer it over a sibling, or any exclusions. Usage is inferable rather than explicit.

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 and openWorldHint, and the description adds genuinely useful behavioral detail beyond them: it performs a HEAD request, validates chain trust and hostname matching, and returns response time. It stops short of noting timeouts, rate limits, or that failures are reported rather than thrown.

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 sentence, front-loaded with the action and the reported result. No filler or redundancy.

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 read-only check with no output schema, the description explains both the mechanism and what is reported. Minor gap: it doesn't state what happens on failure (error vs. negative report) or any timeout behavior.

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 single parameter is fully documented in the schema ('Bare hostname, e.g. example.com'). The description adds no syntax or format detail beyond that, so 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+resource ('Attempt an HTTPS HEAD request to a hostname') and the exact output signal ('whether the TLS handshake succeeded... with response time'). An agent can distinguish this from check_url_status or trace_redirects 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?

No guidance on when to use this versus siblings such as check_url_status or scan_security_headers, and no stated prerequisites (e.g. network reachability, that it does not follow redirects). The purpose is implied by the name, but no explicit when/when-not is given.

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 and network reach are covered. The description adds genuine behavioral context beyond that: redirects are not followed, and HEAD vs GET trade-off is noted, which matters for interpreting the returned status. It stops short of timeout, rate-limit, or error-handling 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?

A single front-loaded sentence that leads with the action, then the method options and constraint, then the return payload. No filler or repetition.

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 two-parameter read-only tool with no output schema, the description enumerates exactly what comes back (status code, status text, response time, headers) and discloses the redirect and method behavior, so 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 description coverage is 100%, including the private/loopback/metadata rejection rule and the method semantics, so the schema does the heavy lifting. The description restates the GET/HEAD choice and redirect behavior but adds no format or syntax detail beyond the schema, matching the baseline for fully documented parameters.

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 ('Request a URL ... return its HTTP status code, status text, response time in ms and response headers'), naming method options and the redirects-not-followed constraint. This implicitly separates it from siblings like trace_redirects and generate_status_url, so an agent can route correctly without opening the 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?

Usage is implied by the tool's narrow scope (check whether a URL is reachable and what it returns). However, no sibling is named and no condition is given for choosing this over check_cors, scan_security_headers, or trace_redirects, leaving the agent to infer the boundary.

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=false, so the safety profile is covered. The description adds genuinely new context on top: it discloses that no signature verification occurs and describes what the response reports (expiry status, seconds until expiry, human-readable iat/nbf/exp). It doesn't mention behavior on malformed or unsigned tokens.

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 operation and immediately followed by the key caveat. Every clause carries information; nothing is repeated from the schema or annotations.

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 usefully enumerates the decoded/reported fields, which an agent needs. It is nearly complete for a one-parameter read tool, with only error behavior for invalid tokens left unstated.

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 there is a single parameter, so the schema already carries the semantics, including the Bearer-prefix stripping and length bounds. The description adds nothing about the token argument. Baseline 3 applies when the schema does the heavy lifting.

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 (Decode) and resource (JSON Web Token) plus scope (header and payload, no signature verification). No sibling tool overlaps with JWT handling (the others are CORS/SSL/DNS/redirect checks), so explicit differentiation isn't needed, but the definition doesn't attempt it.

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 phrase 'without verifying the signature' implicitly signals this is an inspection tool rather than a validation tool, which is a useful boundary. However, there is no explicit when-to-use statement, no prerequisites, and no named alternative for agents who actually need signature verification.

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 and openWorldHint, so the safety and external-network profile is covered. The description adds genuinely new behavioral context: the lookup is performed via Cloudflare DNS-over-HTTPS and the response includes TTLs. It does not mention rate limits or failure behavior for non-existent hostnames, so it stops short of a 5.

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 the core action first and the mechanism/return appended. No filler, no redundancy.

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 does note what comes back (record data and TTLs), and annotations cover the safety profile, so an agent has enough to invoke it correctly. Minor gaps remain around error/empty-result behavior for a 2-param, single-purpose 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 description coverage is 0%, so the description must carry the param burden. It enumerates the record types that map to the 'type' parameter's enum and implies hostname usage, but adds no semantics such as default behavior (A), accepted hostname format, or what happens on lookup failure. Baseline of 3 for a mostly-schema-restated tool.

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 precise verb ('Resolve'), the exact resource (A/AAAA/CNAME/MX/TXT/NS records for a hostname), the underlying mechanism (Cloudflare DNS-over-HTTPS), and the return shape (record data and TTLs). This cleanly separates it from network-diagnostics siblings like check_ssl or trace_redirects without needing to name 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?

The description makes the usage context implicit (DNS record resolution, a diagnostic task) but never states when to reach for this tool versus check_url_status or trace_redirects, nor any prerequisites. Adequate but no explicit when/when-not 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description still adds real context beyond the schema: the serving host (mcp.httpstatus.com) and that it returns both a live URL and an inline sample. It does not state expiry or persistence of the URL, but the safety-critical behavior is clear.

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 tightly packed sentence that front-loads the action and output, then the modifiers. No filler or redundancy; 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 only two parameters, no output schema, and no nested objects, the description covers what the tool returns (a URL plus inline sample) and the conditional count rule. The only omission is any hint about how this relates to the sibling URL-generating 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 50% (count documented, kind is an enum). The description adds meaning beyond the schema by stating that only plural kinds accept count and restating the max of 50, telling the agent the count is conditional on kind rather than always applicable.

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 output ('Return a live URL ... serving placeholder JSON') and enumerates the six kinds, so the agent knows exactly what it produces. It does not explicitly differentiate itself from the similar sibling generate_status_url, which is the only gap.

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 listed kinds and the note that plural kinds accept count, but there is no explicit when-to-use guidance or exclusion relative to generate_status_url, the closest alternative. An agent can infer the context but is not told when to prefer this over siblings.

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=false, so the safety profile is covered. The description usefully adds that the URL is live and that the delay is bounded at 10000 ms, but says nothing about URL lifetime, whether the code/delay are embedded in the path or query, or rate limits on hitting the generated URL.

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, no filler, and the core fact (what is returned) is front-loaded ahead of the supporting use case. 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?

With no output schema, the description carries the burden of describing the return value, and it does say the result is a live URL on a named host. It stops short of showing the URL's shape or noting whether the link is persistent, which is the one gap for a generator 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 description coverage is 100%, and the description largely restates the schema's own bounds (100-599, max 10000 ms). It adds no format or edge-case meaning beyond what the schema documents, 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 gives a specific verb ('Return') and a precisely scoped resource ('a live URL on https://mcp.httpstatus.com that responds with any HTTP status code 100-599'), so an agent immediately understands the output is a URL, not a status check. It does not explicitly differentiate itself from the related sibling generate_dummy_response, which is the only thing keeping it from 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 offers an implied use case ('testing error handling, retries and timeouts') but never states when to prefer this over check_url_status, generate_dummy_response, or the other test helpers. There is no when-not guidance and no named alternative, leaving selection 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 declare readOnlyHint and openWorldHint, so safety is already covered. The description adds genuinely useful behavioral context beyond them: it follows up to 5 redirects and returns a graded n/6 result across named headers, which tells the agent the shape and scope of the 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?

A single dense sentence with the operation front-loaded and no filler; every clause (redirect limit, header list, grading) 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?

With no output schema, the description carries the burden of describing returns and does so concisely by naming the six headers and the n/6 grade. It omits error/failure behavior and the exact response structure, a minor gap for a simple 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?

Only one parameter exists and schema description coverage is 100%, so the schema already documents the url field including its security constraints. The description adds no format or validation detail beyond 'a URL', so the baseline of 3 is appropriate.

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 (Fetch) plus resource (URL security headers) and enumerates exactly which headers are reported with an n/6 grade. This clearly distinguishes it from siblings like check_ssl or trace_redirects, which cover different aspects of URL inspection.

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 purpose — scan a target URL's HTTP security headers — but the description offers no explicit when-to-use guidance or routing against siblings such as check_cors or check_ssl. Nothing is misleading, but the agent must infer selection.

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 cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description goes beyond them by disclosing the hop cap, per-hop report contents, final-URL return, and loop detection. It stops short of stating throttling/rate limits or that private/loopback targets are rejected (that lives only in the 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?

One well-formed sentence, front-loaded with the action and scope, with the return payload attached compactly. No filler or repetition of the name/title.

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 describing returns and does so accurately (per-hop fields, final URL, loop flag), and annotations cover the safety profile. Minor gap: it doesn't mention rejection of private/loopback/metadata URLs, which is relevant observable behaviour, though the schema does.

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% (only 'url' is described). The description adds the 'max 15 hops' bound and the hop semantics of the walk, which maps to maxHops, but it doesn't clarify the default of 10 or the per-hop latency/status semantics in detail. Baseline 3 for partial coverage plus modest added value.

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 (Follow) and resource (a URL through its redirect chain), plus the exact payload it reports (hop URL, status, latency, Location header, final URL, loop flag). This reads clearly as distinct from siblings like check_url_status or check_ssl, which don't walk the redirect chain.

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: an agent can infer this is for diagnosing redirect behaviour, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. when a simple status check suffices). No prerequisites or error conditions are stated.

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