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 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 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, 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.