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

With no annotations, the description carries the full burden and does so: it declares WRITE semantics, the digest re-verification against a freshly recomputed plan, the backing up/atomic-with-lock/verify/rollback behavior, the guarantee that a failed apply leaves the original config in place, all five outcome values, and negative guarantees (installs no components, leaves no persistent files, never connects to the server).

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?

Single front-loaded paragraph that leads with the action, then prerequisites, then failure/rollback guarantees, then outcomes. Dense but nearly every clause adds operational information; the outcome enumeration and negative guarantees could be tightened slightly.

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 high-risk destructive write with no annotations and no output schema, the definition covers prerequisites, refusal conditions, atomicity/rollback, outcome vocabulary, and what happens afterward (decision receipt returned inline). Nothing an agent needs to invoke it correctly 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%, so the baseline is 3, but the description adds genuine cross-parameter meaning the schema only hints at: approvalDigest must equal the planDigest returned by prepare, and the host must be a supported value or the call refuses. It does not enumerate per-parameter format beyond what the schema already documents.

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 ('Apply an install plan ... writing the pinned MCP server into a host's config') and immediately differentiates itself from siblings by declaring it is 'the only CallLint tool that changes a file.' An agent can distinguish it from calllint_prepare_safe_install and verify_baseline 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?

Explicitly names the prerequisite ('a plan you already prepared and explicitly approved') and the producing sibling (calllint_prepare_safe_install), plus the exact conditions that select refusal: unsupported host, missing/mismatched approvalDigest, public BLOCK/UNKNOWN/unsupported route, local BLOCK/UNKNOWN, exact-target mismatch. When and when-not are both stated.

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?

With no annotations, the description carries the full burden and mostly does: it declares the tool is a pure read despite the 'enable' name, that approvalDigest cannot authorize an install, and that persistence is why enabling is a separate decision. It stops short of stating error behavior (e.g. unrecognized hosts) or any latency/permission requirements, but covers the critical non-destructiveness claim.

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?

Dense but disciplined: purpose first, then the persistence rationale, then the safety disclaimer, then the reporting instruction. Every sentence contributes, though the middle clause ('re-decide the approved agent-tool authority surface, detect drift, re-check upgrades') is more internal detail than an agent needs to select the tool.

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?

No output schema exists, and the description compensates by enumerating the return payload (component, file created, enable command, remove command, disclosureDigest, disableCommand). Combined with the no-side-effects guarantee, an agent has everything needed to call it and act on the result 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 both parameters are already fully documented. The description reinforces approvalDigest's non-authorizing role ('even if you pass approvalDigest') and mentions host-dependence, but adds no syntax or selection detail beyond the schema — 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?

Opens with a precise verb+object ('List exactly what CallLint's continuous protection would install') and immediately resolves the misleading 'enable' in the tool name by stating it 'writes nothing, enables nothing, and installs nothing.' It also distinguishes itself from a one-time install and from the apply path, so an agent can place it among the calllint_* 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?

States the decision context (so a person can decide whether to enable), the required follow-through ('Report the components and both choices — enable, or not now — and let the person run the enable command themselves in a terminal'), and the alternative of declining with its consequence. This is explicit when/when-not guidance rather than 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?

With no annotations provided, the description carries the full burden and does so thoroughly: it discloses that the contract is served verbatim from a committed bundle, that there is no network, execution, or new verdict, that a version mismatch returns not-found rather than a different version, and that absence is not a verdict. It also enumerates the return contents (pinned subject, public observation, authority delta, recommendedNextAction), so the agent knows exactly what behavior to expect.

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 and every section contributes something, but the description is a dense single paragraph with some redundancy, such as restating that the contract is the exact machine contract already published and separately describing its contents. It is appropriately sized for a tool with no annotations and no output schema, though it could be trimmed slightly.

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 that there are no annotations and no output schema, the description supplies everything an agent needs: the source of the data, the read-only and offline behavior, the exact return fields, the not-found and absence semantics, and the recommended next action. Nothing material is missing 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 coverage is 100%, and both the canonicalName and version parameters are already fully described in the schema, including the mismatch-returns-not-found semantics. The description reinforces the canonicalName relationship to calllint_search_agent_tools and repeats the exact-version pin behavior, but adds no syntax or format detail beyond what the schema already 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?

States a specific verb and resource ('Fetch the committed CallLint Agent Adoption Contract') and immediately scopes it to published MCP servers/agent tools by canonical name. It also distinguishes itself from siblings by naming calllint_search_agent_tools as the source of the slug and calllint_prepare_safe_install as the follow-up.

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 says when to use it ('to obtain the exact target to assert, then calllint_prepare_safe_install to re-decide locally before any install') and when a result will not be served ('a resource with no committed contract is not served; absence is not a verdict'). The alternative and the sequencing are both spelled out.

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?

With no annotations, the description carries the full burden and does substantial work: deterministic rules, never an LLM, never executes the judged server or tool, no side effects, and the crucial semantic that UNKNOWN is never equivalent to SAFE. What is missing is any statement of the return shape of this specific call (what 'reports availability' actually yields).

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?

Roughly 170 words for a no-input discovery stub, with the tool's actual behavior stated only in the last sentence. The verdict semantics and sibling inventory are genuinely useful context, but the front-loading is inverted and the sentence about being 'a pure delegator, ADR 0025' is internal jargon that does little for an agent.

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?

No annotations, no output schema, and no parameters mean the description must supply all behavioral context, and it does: it explains verdict tiers, determinism, non-execution, and where to go next. It is close to complete, lacking only a note on what this call returns or costs.

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 has zero parameters and full coverage, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly signals no input is expected by describing a pure presence report.

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 final sentence states the specific function: 'This tool only reports that CallLint is available; it changes no verdict and performs no action of its own.' It also enumerates the sibling tools and their distinct roles, so an agent can separate this discovery stub from the workers. The only weakness is that the tool's own verb is buried at the end behind a long preamble about CallLint as a product.

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 mapping of siblings to jobs (scan_mcp_config_json/path for a verdict, explain_finding for evidence, verify_baseline for drift, generate_* for wiring) implicitly routes an agent away from this tool for real work. However, it never states explicitly when to call this tool versus going straight to scan_mcp_config_path, leaving the usage condition inferred rather than declared.

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?

With no annotations, the description carries the full burden and does: read-only planning, no execution, no config writes, local verdict can only be stricter than public, refusal order (public BLOCK/UNKNOWN refused before re-decode, mismatch aborts with no plan). It enumerates every terminal outcome (PREPARED, BLOCKED, LOCAL_PREFLIGHT_REQUIRED, ABORTED_ON_MISMATCH, UNSUPPORTED), which is exactly the behavioral surface an agent needs.

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-loaded with the action and scoping constraint in the first sentence; every subsequent clause carries real information. It is dense and parenthesis-heavy, which makes the outcome list harder to scan, but there is no 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?

No output schema exists, and the description compensates by enumerating the five possible outcomes and describing what a PREPARED result contains (an inert, non-authorizing install plan). For a six-parameter, multi-stage static analysis tool, an agent has everything needed to call it and interpret the result.

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 baseline is 3 and the schema already explains host enum values, hostConfigPath read-only behavior, and digest formats. The description adds only marginal meaning — that digests exist to 'assert you got the target you meant' and that naming a host produces the inert plan — but does not extend parameter behavior 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 specific verb and resource ('Locally and statically PREPARE a safe install of a published MCP server') plus the exact scope constraint ('before anything is written'). It also distinguishes itself from the sibling calllint_apply_prepared_install by declaring the plan 'authorizes nothing on its own' and that applying is a separate human-gated step.

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 says what to supply (canonical name, ideally digests from calllint_get_adoption_contract) and routes callers away when inapplicable: only a pinned npm subject is auto-preparable, anything else returns LOCAL_PREFLIGHT_REQUIRED and should use `calllint trust prepare`. It also states the negative space clearly — never executes, never writes config.

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?

With no annotations, the description carries the full burden and does so: deterministic exact/prefix/substring tiering with alphabetical ordering, no LLM or semantic ranking, no new score, no execution, no verdict changes. It also pre-empts misinterpretation ('not a certification... absence is not a verdict') and explains the meaning of every verdict value.

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 and matching behavior are front-loaded and the sentences are dense with content rather than filler. It is long, and the trust disclaimers ('authorizes nothing', 'not a certification, an endorsement, or a guarantee') overlap enough that one could be trimmed.

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 search tool with no output schema, the description enumerates the returned fields (verdict, label, digest, observed-at, Trust Page URL, and the optional installUrl/contractUrl/installability triple). Nothing an agent needs to interpret or correctly call the tool appears to be 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%, so the baseline is 3, but the description adds genuine meaning: query matching follows an exact-then-prefix-then-substring tier order, and ordering within a tier is alphabetical. It does not restate the limit semantics beyond what the schema already documents.

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: search already-published CallLint Trust Pages for MCP servers and agent tools by name, returning each match's existing verdict. It further distinguishes itself from the sibling scan_mcp_config_json by scope (published pages vs. a config with no page yet).

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 alternative and the condition that selects it: 'To scan a config that has no page yet, use scan_mcp_config_json.' It also sets expectations that non-indexed resources simply do not appear, preventing misreading absence as a result.

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?

With no annotations, the description carries the full burden and does so explicitly: writes nothing, runs no scan, applies no policy, decides no verdict, never starts or connects to the server. It also discloses drift handling ('reported, never accepted') and the expired-receipt semantics, which an agent could not infer from any structured field.

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-loaded with the purpose, then the read-only constraint and the return conditions. The negation list is a little repetitive but each clause rules out a distinct misconception; nothing is redundant enough to hurt.

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, and the description compensates by enumerating what the check reports: config existence/parsing, presence of the expected entry, and whether the entry still pins the exact package@version. Combined with the explicit non-verdict caveat, an agent has everything it needs to call this 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 parameters are already documented and the baseline is 3. The description adds only marginal meaning beyond the schema — it clarifies why the receipt exists and how expiration is treated — but says nothing extra about hostConfigPath or the cursor scoping requirement.

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?

It states a specific verb and resource — 'verify that an MCP server install is actually in place and unchanged' — plus the mechanism (reading host config, comparing against the contract's pinned target). This distinguishes it from siblings like scan_mcp_config_path or calllint_apply_prepared_install, which mutate or scan rather than verify a specific entry against a contract.

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

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

Usage is clearly framed: read-only post-install verification, with the receipt option tied explicitly to calllint_apply_prepared_install. It also draws the boundary that a passing check is not a safety verdict, which is a useful exclusion. It stops short of naming a sibling to prefer in a given situation, 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?

With no annotations provided, the description carries the full burden. It accurately states the tool returns an explanation, which implies a read-only operation, but it does not disclose any potential side effects, prerequisites, or limitations (e.g., whether it requires a prior scan or if it modifies anything). The description is basic but not misleading.

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

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

The description is a single, front-loaded sentence that precisely conveys the tool's purpose without any redundant words or filler. Every clause adds value, making it highly concise and well-structured.

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 straightforward explanation tool with simple parameters and no output schema, the description is sufficiently complete. It adequately explains what the tool does and its scope. A minor gap is the lack of explicit guidance on when to use it relative to sibling tools, but this does not undermine the overall completeness given the tool's simplicity.

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 description coverage is 100%, so the baseline is 3. The description adds context by framing the json parameter as an 'MCP config JSON' and clarifying that the explanation covers 'each verdict', but it does not enrich the meaning of the server or surface parameters beyond what the schema already states (default all, optional label).

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 the specific verb 'Return' and clearly identifies the resource as 'full evidence-backed explanation for the servers in an MCP config JSON'. It also conveys the key differentiator from siblings (e.g., scan_mcp_config_json returns findings, this explains the reasoning), making the purpose 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 description implies this tool is used after a scan to get the reasoning behind verdicts, but it does not explicitly state when to use it versus alternatives like scan_mcp_config_json or verify_baseline. No exclusions are mentioned, and the intended context is only implicit through the phrase 'why each verdict was reached'.

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?

No annotations are provided, so the description carries the transparency burden. It usefully indicates that the output is paste-ready rule text, but it does not describe side effects, output structure, or whether the tool writes files. It is adequate but not rich.

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 one concise, front-loaded sentence that conveys purpose, target, and output use without wasted words. It 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 simple one-parameter generation tool, the description plus schema adequately define the task and expected output. It could mention output format or explicitly say it does not modify files, but these are not essential gaps.

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 host parameter is fully documented with an enum and explicit allowed values. The description only repeats example hosts and adds no additional meaning or constraints 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?

The description clearly states the tool generates CallLint agent-safety rule text for a specified host, using a specific verb and resource. It distinguishes itself from sibling tools like scanning or verifying MCP configs by focusing on output generation for host rule files.

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 practical context by mentioning examples of hosts and saying to paste the result into a rules file, but it does not explicitly contrast this tool with alternatives like generate_ci_gate_snippet or explain_finding. Usage is implied rather than directly guided.

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?

With no annotations, the description carries the behavioral burden. It usefully discloses that drift mode fails on approved-state drift while scan-all is report-only, which is helpful. However, it omits other relevant behavioral details such as whether the snippet is returned or written to disk, any side effects, or required permissions exactly.

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 compact sentences, no filler. The first sentence states what the tool generates; the second explains both mode semantics. Every sentence adds value and the structure is front-loaded.

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

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

For a simple one-parameter tool with an enum schema and no nested objects, the description is mostly complete. It explains the generated artifact, its purpose, what the modes do, and the repo behavior is sufficient. Given there is no output schema, a bit more detail about return shape or exact effect would lift it higher, but it is still adequately complete.

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 input schema already covers the only parameter with high confidence: mode has an enum and default. The description also restates both modes and adds the behavioral implication (fail vs report-only), but it does not provide any hidden semantics beyond what the schema already contains. This matches the expected baseline for full schema coverage.

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 action ('Generate a GitHub Actions workflow') and names the exact file path (.github/workflows/calllint.yml). It also communicates the core function — gating a repo on its agent-tool surface — which clearly differentiates it from the sibling tools like scan_mcp_config_json or generate_agent_rule.

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 explains the two modes (drift and scan-all) but does not say when to use this tool versus alternatives or when one mode should be preferred over the other. No explicit exclusions, prerequisites, or situational guidance is provided.

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?

With no annotations provided, the description carries the full burden. It explicitly discloses that the tool is static and never executes the server, which is crucial safety information for an AI agent. It also hints at the output format (compact decisions) without relying on an output schema. This goes beyond a minimal description, though it doesn't cover all potential side effects (e.g., network access, error behavior).

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

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

The description is a single, compact sentence that packs in the verb, resource, output summary, and a critical safety note. There is zero fluff and it's immediately understandable.

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?

The tool is relatively simple (2 params, no output schema), and the description covers the core functionality and safety. It could improve by mentioning the exact structure of the returned decisions or any limitations (e.g., only works with JSON, not other configs), but given the low complexity and high schema coverage, the description is sufficiently complete.

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% (both parameters have descriptions), so the schema already documents the parameters. The description adds context for the 'json' parameter by specifying it expects raw MCP config JSON, and the 'surface' parameter is an optional label with an example. The description adds the context that the tool returns decisions, but doesn't delve into parameter format specifics beyond schema. Given high schema coverage, this is a solid 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 clearly states the tool's purpose: scanning MCP config JSON text and returning per-server decisions with verdict, fingerprint hash, and reason codes. It also clearly distinguishes itself from a sibling tool by noting it's static and never executes the server, which differentiates it from scan_mcp_config_path.

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 usage for static analysis of MCP config text, with the explicit note 'never executes the server' serving as a safety guideline. It differentiates from the sibling scan_mcp_config_path by clarifying it operates on text input rather than a path, which is useful. However, it doesn't explicitly state when to prefer this tool over the path-based sibling.

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?

No annotations are provided, so the description carries the full behavioral burden. It explicitly discloses the key safety property: 'Static; never executes the server.' It also states the return value, though it does not cover error cases, file permissions, or path-resolution 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?

Two concise sentences front-load the core action and output while adding a valuable safety qualifier ('Static; never executes the server'). Every sentence earns its place with no wasted 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?

For a simple one-parameter tool with no output schema, the description is complete: it explains what is scanned, what is returned, and the key safety restriction. No essential behavior is left unexplained at this complexity level.

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 baseline is 3. The description adds 'on disk' context and the static/no-execution behavior, but it does not add parameter format or path-handling details beyond the schema's 'Path to the MCP config file.'

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 ('Scan'), identifies the exact resource ('MCP config file on disk'), and states the concrete output ('full ScanReport (verdict + evidence)'). It differentiates from the sibling tool scan_mcp_config_json by emphasizing that this operates on a file on disk.

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 provides clear context: use this tool to scan an MCP config file that lives on disk. It does not explicitly name alternatives or state when not to use it, though 'on disk' and the sibling name scan_mcp_config_json imply the JSON-string alternative.

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 adds one key behavioral trait: 'Static; never executes the server.' However, it does not disclose other aspects such as output format, potential side effects, or error handling. With no annotations, the description carries full burden and falls short of full transparency.

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 only two sentences, highly concise, and front-loaded with the core purpose. Every part adds value, and there is no extraneous text.

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 lack of output schema, the description does not specify the format of the reported drift or signals. While it covers the static nature and basic operation, it is incomplete regarding what the agent should expect as a return value or how to 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?

The input schema already provides 100% coverage with descriptions for all three parameters. The description adds extra meaning for the 'baseline' parameter by explaining its optional behavior ('if omitted, a baseline is built...'), which goes beyond the schema's description. This justifies above the baseline of 3.

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

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

The description clearly states the tool's action ('Compare a fresh scan... against a recorded baseline'), the resource (MCP config JSON), and the result ('report drift / rug-pull signals'). It also explicitly notes it's static and never executes the server, which distinguishes its purpose well.

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 usage for baseline verification but provides no explicit guidance on when to use versus alternatives or when not to use. Since no sibling tools exist, the lack of differentiation is acceptable, but it could still benefit from context on prerequisites or limitations.

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