Toolbox

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. Beyond that, the description discloses the actual working behavior: it fetches robots.txt from the live site (open-world network read), inspects llms.txt, and goes further by generating a draft llms.txt from site metadata and sitemap – a non-obvious generative action that the agent would not infer from the annotations. It stops short of describing failure modes (unreachable site, missing robots.txt), which keeps it out of 5 territory.

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 sentence with the primary robots.txt/crawler-reporting action front-loaded and the llms.txt drafting noted second. The parenthetical crawler enumeration is useful but makes the sentence long; it is dense without being redundant.

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

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

With no output schema, the description must convey what comes back, and it does: allowed/blocked/partially-blocked status per crawler plus llms.txt presence and a draft. For a one-parameter, read-only tool this is close to sufficient; only return-shape specifics and error behavior are left unspecified.

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 param is documented as 'Any URL on the site', so the schema already carries the semantics. The description reinforces that the unit of analysis is the site (not an individual page), adding minimal but non-zero meaning. 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 and resource (read robots.txt, report AI crawler access status) and even enumerates the concrete crawlers checked (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, CCBot, Bytespider). The secondary action – checking for and drafting an llms.txt – is also named, so the agent knows exactly what the tool returns. No sibling overlap exists among check_tells, lint_agent_md, manifest_cost or mcp_install_snippets.

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 description (use it to learn whether AI crawlers may access a site), but there is no explicit when-to-use, when-not-to-use, or named alternative. The sibling list contains no competing crawler-access tool, so the absence of routing guidance is a minor gap rather than a harmful one.

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 and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: a single network fetch ('once'), and the shape of the result (grade, score, and the exact header to add per gap), which matters because there is no output 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?

Two sentences, front-loaded with the action, followed by the graded-header list and the return shape. The enumeration is dense but every listed header is substantive; nothing is redundant filler.

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

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

With one parameter, full schema coverage, and annotations covering the safety profile, the main remaining burden is describing the return value, which the description does (grade, score, per-gap remediation). Edge cases such as unreachable URLs, redirects, or timeouts are not addressed, but the definition is otherwise sufficient to call 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 coverage is 100% with a single documented 'url' parameter, so the schema carries the parameter burden. The description only adds that the URL is fetched once and its response headers inspected; it adds no format, protocol, or redirect-handling detail beyond the schema.

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 concrete verb+resource ('Fetch a URL once and grade its response headers') and enumerates exactly which headers are evaluated (HSTS, CSP, X-Content-Type-Options, cookie flags, etc.). This implicitly separates it from check_page_meta and check_ai_crawlers, but it never names or explicitly routes away from those siblings.

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

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

The description says what the tool does but gives no when-to-use context, no prerequisites, and no comparison to alternatives such as check_page_meta or check_ai_crawlers. The agent must infer the use case (security-header auditing) entirely from the purpose statement.

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, openWorldHint=true, destructiveHint=false, so safety and network reach are covered. The description still adds real behavioral value: it discloses that output includes derived "findings for anything missing or too long," i.e. a verdict rather than raw HTML, which the annotations cannot convey. It does not mention failure modes (unreachable URLs, non-HTML responses, timeouts), which would have earned 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 sentence, front-loaded with the verb and the inspecting-subject ("what crawlers and link unfurlers see"), followed by a compact enumeration. The long list is justified because there is no output schema, so it is disclosure rather than padding. Slightly dense but zero filler 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?

With no output schema, the description correctly compensates by enumerating the return contents, including the computed preview card and findings. What is missing for a network-fetching tool is error/boundary behavior (timeouts, non-HTML, redirects) and the sibling routing decision, keeping it short of a 5.

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?

One parameter with 100% schema description coverage ("The page to fetch"), so the schema does the work; baseline 3 applies. The description adds no URL format, redirect, or scheme guidance beyond what the schema already says.

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 concrete verb+resource ("Fetch a URL and report") and enumerates exactly what is inspected: title, meta description lengths, canonical, lang, viewport, robots meta, h1s, OG/Twitter tags, favicon, JSON-LD, preview card, findings. Purpose is unmistakable, but there is no differentiation from siblings that also fetch and inspect a URL (check_headers, check_ai_crawlers, check_tells), so an agent must guess which checker applies.

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?

There is no when-to-use statement and no named alternative. With three sibling tools that also take a URL and inspect a page (check_headers, check_ai_crawlers, check_tells), the description should say which concern it owns (SEO/social metadata vs headers vs crawler policy). The enumerated outputs imply the domain but never route the agent.

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, openWorldHint=true, and destructiveHint=false, but the description adds substantial behavioral detail beyond that: discovery order, reading index files one level deep with a 20-child cap, HEAD-then-GET sampling, and specific flags for missing sitemaps, robots.txt gaps, URL limits, and host mismatches.

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 purpose is front-loaded before the operational details, and every clause contributes useful information. It is dense as a single long sentence and could be more scannable, but it avoids waste.

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 must explain return values; it does so at a high level by describing URL counts per file and host, lastmod summaries, non-200 sample counts, and flags. Exact output shape and auth/rate-limit behavior are not covered, keeping it below 5.

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 url and sample parameters are already documented in the schema. The description confirms sampling behavior but does not add syntax, default, or max details beyond what the schema provides, so the baseline 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?

The description uses a specific verb and resource: 'Check a site's sitemaps.' It then enumerates the discovery sources and checks performed, making it clearly distinct from sibling tools like check_headers or check_page_meta.

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 purpose implies when to use it, but there is no explicit guidance about when to choose this tool over alternatives such as check_headers or check_page_meta, nor any stated exclusions. Usage is reasonably inferred from the resource but not directly taught.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, closed world), so the bar is lower. The description adds real value by disclosing the return shape — a score, each tell with its position, and a cleaned copy — which matters because no output schema exists. It does not mention rate limits or cost behavior beyond the schema's char limit, so not 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?

Two sentences, front-loaded with the action and the detection list, followed by the usage trigger. The long parenthetical is justified because it disambiguates what 'tells' means, but it is dense enough to keep this from a clean 5.

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?

A single-parameter, read-only tool with no output schema, and the description steps in to describe the return payload (score, positioned tells, cleaned copy) and the intended usage context. Nothing critical is missing for an agent to invoke it correctly, though the absence of any output schema means more return-detail could have helped.

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's schema already documents the text input and free-tier 3,000-char limit. The description adds no additional syntax, format, or constraint detail for the parameter, 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?

Specific verb (check) plus resource (text for AI-writing tells) with an enumerated list of the exact patterns detected (em-dashes, 'not just X but Y', rule-of-three, stock vocabulary, hedge words, smart quotes, hidden Unicode). This is far more discriminative than the sibling names (check_ai_crawlers, lint_agent_md) and an agent can tell the tools apart immediately.

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 closing sentence gives a clear trigger: 'Run it on anything you are about to publish on a human's behalf.' That is strong positive guidance for when to use it. There is no explicit when-not or named alternative (e.g., lint_agent_md vs this), so it falls 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.

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

Annotations already establish read-only, non-destructive, closed-world behavior, and the description adds substantial value on top: the exact output shape (ISO times for iat/nbf/exp, expiresIn, issuer/subject/audience) and a concrete enumeration of security findings it surfaces (alg none, HS* with URL-like kid, off-site jku/x5u, oversized payloads, sensitive field names). That is far beyond annotation coverage.

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?

Purpose is front-loaded and every clause carries information — the difference is that the return/findings enumeration is packed into one long run-on sentence rather than being broken out, which slightly hurts scanability but wastes no words.

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 must describe returns, and it does so in detail, including the findings taxonomy. For a single-parameter, read-only tool this leaves nothing an agent needs 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?

One parameter at 100% schema description coverage, so the schema already documents the token format and the ignored 'Bearer' prefix. The description adds no parameter-level detail beyond the schema, which is the expected baseline here.

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 (JWT header and payload) plus the critical scope limit that the signature is not verified. No sibling does anything similar, and the tool's boundary is unambiguous.

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 parenthetical 'it never takes a secret' and 'without verifying the signature' effectively tell the agent when NOT to reach for this tool (any real trust/verification decision). It stops short of naming an alternative verification path, but no sibling offers one, so context is adequate.

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 a safe read-only, closed-world operation, so the safety profile is covered. The description adds real behavioral context beyond them: results are computed in UTC and the tool flags platform-specific cron divergences (nicknames, six fields, day-31), which an agent could not infer from 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?

A single front-loaded sentence that names the core action first, then the two secondary outputs. Every clause carries information; nothing is boilerplate or redundant.

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

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

With no output schema, the description must describe returns, and it does: plain-English explanation, next-run list in UTC, and dialect warnings. For a focused read-only utility this is fully sufficient for correct invocation.

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 'expression', 'from' and 'count' including their defaults and ranges are already documented in the schema. The description adds nothing about parameter syntax or the accepted expression format beyond what is structured, so the baseline 3 applies.

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

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

The description states a specific verb (explain) and resource (five-field cron expression) and enumerates the three outputs: plain-English explanation, next runs in UTC, and dialect warnings. It is unmistakably distinct from every sibling tool, none of which touch cron.

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 clear context for what the tool covers (five-field expressions, UTC next runs, dialect pitfalls), which tells an agent when this is the right tool. It stops short of explicit when-not-to-use guidance, but no sibling overlaps, so the omission is minor.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false, destructiveHint=false), so the description's job is to add substance beyond that—and it does, listing exactly what is inferred: required vs optional keys across samples, nullability, integer vs number, format detection, and small enums. It still doesn't say how invalid or malformed JSON is handled, which is the main remaining gap.

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 dense sentences, front-loaded with the transformation and followed by the inference capabilities and the intended use case. Every clause carries information; nothing is padding.

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

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

With no output schema, the description must convey the return values, and it does name both artifacts (JSON Schema draft 2020-12 and a TypeScript type). Combined with the stated inference behavior, an agent has enough to call it correctly; only error/failure behavior is unaddressed.

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 two parameters (json, name) are already documented, establishing a baseline of 3. The description adds only one marginal semantic detail—that the JSON text may be an array of samples of the same shape—which is not obvious from the schema's 'JSON text' wording.

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 transformation: JSON sample(s) in, JSON Schema draft 2020-12 plus a TypeScript type out. The verb+resource pair is unambiguous, and no sibling tool (check_headers, lint_agent_md, explain_cron, etc.) overlaps with 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?

Explicitly names the use case: 'draft an MCP tool inputSchema from an example payload.' That gives clear context for when to reach for it. It does not state when not to use it, but among the siblings there is no competing alternative to exclude.

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 destructiveHint=false, so safety is covered; the description adds real behavioral value by enumerating the seven check categories it performs (line cap, tokens, duplicates, contradictions, TODOs, hidden chars, empty headings). It doesn't say how results are returned or whether severity gating applies.

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 verb first and a compact colon-delimited list; nothing is redundant. It is slightly dense but every listed check 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?

For a read-only, two-parameter linter with no output schema, the description gives enough for correct invocation — the checks enumerated effectively foreshadow the report contents. Only return-shape and severity behavior are left unspecified, which is a minor gap.

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 both parameters are already documented; baseline is 3. The description only indirectly touches the filename parameter by naming the 200-line memory index cap, without adding format or severity semantics beyond the schema.

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?

Specific verb ('Lint') plus a precise resource set (CLAUDE.md, AGENTS.md, MEMORY.md), and the enumerated checks make the scope unambiguous. It is trivially distinguishable from siblings like check_ai_crawlers or manifest_cost.

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 resource type — you run it on a memory/instruction file — but the description never states when to reach for this tool versus the sibling checks, nor any prerequisites (e.g., run before committing). No exclusions or alternatives are 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, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds that it operates "from the model's side of the wire," that it will call a live endpoint, and the exact checklist of findings it emits including the ^[a-zA-Z0-9_-]{1,64}$ rule, which is genuine added 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?

Front-loads the verb and resource, then packs the lint rules into one dense list without filler. The enumeration is long but each clause names a distinct check, so it earns its space; only minor tightening is possible.

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 finding categories an agent can expect, and it explains the input paths. Return formatting and whether findings are warnings vs. errors are still left implicit, but the tool is simple enough that nothing critical is missing.

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

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

Schema coverage is 100% with both parameters documented, so the schema baseline is already adequate. The description goes slightly beyond it by framing url and tools as alternative invocation paths (live endpoint vs. supplied array), clarifying the either/or relationship the schema does not state.

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 (lint) and resource (the tools an MCP server lists) and enumerates the concrete defects it detects, from name-regex violations to destructive tools missing destructiveHint. This clearly separates it from flanking siblings such as lint_agent_md, json_to_schema, and check_* tools, which target different artifacts.

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?

"Pass a live Streamable HTTP endpoint or a tools array" tells the agent the two supported invocation modes and when each applies, which is real routing guidance. It stops short of explicit when-not-to-use conditions or naming alternatives, but the distinct resource makes exclusions less necessary.

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, openWorldHint=true, and destructiveHint=false, and the description goes further by disclosing the report contents (top-3 expensive tools, size/pattern flags) rather than just restating that it reads. It omits any mention of auth requirements, rate limits, or whether the endpoint is actually contacted (network side effects of openWorldHint), leaving a small gap.

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 tight sentences: the first front-loads purpose and output shape, the second covers the two input modes. No filler, no redundant restatement of the 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 concretely (per-tool cost, top three, three flag categories). It does not specify the report format or units/scaling of the token estimate, which is a minor remaining gap for a low-complexity two-parameter read 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% and both parameters are already documented as 'Streamable HTTP MCP endpoint' and 'Tool definitions'. The description largely restates those, adding only the condition that the tools array is used 'if the server is not reachable over HTTP', which is a marginal gain over the schema.

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 (Estimate) and resource (token cost of an MCP server's tools/list manifest), and enumerates the concrete outputs: per-tool cost, three most expensive tools, and flags for oversized descriptions, base64 blobs, and echoed schemas. An agent immediately knows what the tool produces; no sibling overlap exists to disambiguate.

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?

Implies the use case ('on every session start') and tells the caller how to invoke it in two modes: a live Streamable HTTP endpoint or a tools array. It does not name a when-not condition or point to an alternative, but the sibling tools (crawler checks, linting) are unrelated, so no routing guidance is genuinely needed.

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, openWorldHint=true, and destructiveHint=false, and the description is consistent with that safety profile. It usefully adds that a network probe is performed against the endpoint, but it does not say what happens if the probe fails, that probing is optional, or how auth headers affect the request. Tension with the probe=false default is left unexplained.

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 primary action front-loaded and the probe detail trailing. No filler text, though the parenthetical client list makes it slightly long for one sentence.

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 5-parameter tool with 20% schema coverage and no output schema, the description covers only the happy path. It omits the header parameters (critical for probing authenticated endpoints), the probe toggle, and any indication of the snippet format or how probe results are reported.

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 only 20% (only 'name' is documented), so the description must compensate for url, probe, headerName, and headerValue. It mentions none of them explicitly, leaving the header-based auth mechanism and the ability to disable probing entirely invisible to the agent.

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 ('Generate install snippets for an MCP endpoint') and enumerates the client targets, then names the secondary action of probing the endpoint via initialize and tools/list. An agent immediately knows what comes back, and the unrelated siblings (check_ai_crawlers, lint_agent_md, etc.) create no ambiguity to resolve.

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 and by the required url parameter, but there is no explicit when-to-use or when-not guidance, no stated prerequisite (e.g. a reachable endpoint), and no note that the probe can be skipped. With no overlapping siblings, the implied usage is adequate but nothing more.

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 a safe read-only, non-destructive operation, and the description goes well beyond them: it explains exactly how values are mutated (blanked or shape-preserving placeholders), what the return payload contains, and the privacy-conscious truncation to 'first 4 characters and the length'. That level of disclosure about output content and secret handling is exactly the added value structured fields do not provide.

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 dense sentences, front-loaded with the core transformation before the return details. The long provider enumeration is informative rather than wasteful, though it makes the second sentence heavy and could be compressed.

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 present, the description carries the full burden of explaining return values and does so thoroughly: the example output, the secrets structure (key, kind, line, truncated value), and the separate findings list. An agent has everything needed to call and interpret results.

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?

There is a single parameter whose schema description already covers it at 100% (including the free-tier char limit). The description adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 for a fully documented schema is correct.

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 (scrub a .env file) plus the concrete output form (.env.example), and the placeholder example 'postgres://USER:PASSWORD@HOST/DB' makes the transformation unambiguous. No sibling in the list does anything similar, so the agent can route to it without opening any schema.

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

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

The purpose implies the use case (turning a real .env into a shareable example), but there is no explicit when-to-use statement, no prerequisites, and no named alternatives or exclusions. Usage is only inferable from the description of what the tool does.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered; the description goes well beyond by disclosing the hop cap (10), per-hop timeout (8s), the exact fields returned per hop (status, location, timing, scheme), and every anomaly it detects. It stops short of stating failure/timeout behavior for the trace itself, which keeps it from 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 that leads with the action and adds the hop/time limits before the flag list. It is dense and long, but each clause (limits, per-hop fields, detected anomalies) carries distinct information; only the flag enumeration risks becoming a run-on.

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 read-only, open-world network tool with a trivial one-parameter schema and no output schema, the description supplies enough: what it walks, its limits, and the per-hop payload fields. It does not cover behavior on unreachable hosts or timeout exhaustion, a minor residual gap.

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?

There is only one parameter and schema description coverage is 100% ('URL to trace, e.g. http://example.com'), so the schema already carries the semantics. The description adds contextual constraints about how the URL is probed but nothing about the url parameter's accepted forms, so the baseline 3 is right.

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?

Names a specific verb and resource ('Trace a URL's redirect chain hop by hop') and immediately scopes it with limits (10 hops, 8s each) and per-hop fields. It is unmistakably distinct from every sibling (check_headers, check_sitemap, check_tells, etc.), none of which trace redirect chains.

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 enumerated flags (loops, HTTPS-to-HTTP downgrades, 302 canonicalisation, dropped paths/query, cross-domain moves, meta-refresh/JS on 200, non-200 final page) imply the use case: auditing redirect hygiene. However, there is no explicit when-to-use statement, no exclusions, and no reference to an alternative tool for related diagnostics.

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