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

With no annotations, the description carries the full burden. It usefully discloses the return payload shape ({pass, score_0_100, errors, warnings, recommendations, spec_version}), which compensates for the absent output schema, but says nothing about side effects, permissions, or whether the audit is purely read-only.

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 one-line purpose and then uses compact Args/Returns blocks with no filler. Efficient, though the Args section largely restates the two parameters already visible in the schema.

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 two-parameter tool with no annotations and no output schema, the description covers both inputs and enumerates the full return structure. It stops short of clarifying how the 'full' audit relates to the sibling partial checks.

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 0%, so the description must compensate and largely does: it explains server_json as the contents of a server.json file and spec_version as the target spec revision with a default. The only gap is a minor drift where the description says the default is 'latest' while the schema pins '2025-12-11'.

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 ('Full conformity audit of an MCP server.json'), and the word 'Full' implicitly distinguishes it from the piecemeal sibling checks like check_required_fields and check_naming_conventions. It does not name any sibling explicitly, so it falls short of a 5.

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

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

No when-to-use guidance, no prerequisites, and no routing between this and the four sibling check tools. An agent must infer that a 'full' audit supersedes the granular checks.

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 burden. It does disclose the return shape ({pass, issues}), which is useful, but it does not state that the operation is non-destructive, whether it mutates or reads server_json, or any failure behavior. A lint-style tool is implicitly read-only, but this is inferred rather than stated.

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 one-line purpose followed by compact Args/Returns blocks lifted from the docstring. Every element is short, though the Args entries are close to repeating the schema titles.

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?

It supplies param meaning and the return shape ({pass, issues}) despite having no output schema, which covers the essentials. With a free-form nested server_json object and no annotations, it still leaves the expected input structure and the nature/magnitude of reported issues undescribed.

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

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

Schema description coverage is 0%, so the description must compensate, and it partially does: tool_names is clarified as an optional list validated against snake_case, and server_json as server.json contents. However, 'server.json contents' is near-tautological and gives no hint about the expected slug/version structure inside the nested object.

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 the exact resources checked: slug, version, and tool names. That is clearly distinguishable from sibling checks like check_required_fields or audit_server_json, though the description never names those siblings explicitly.

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: validate a server.json against naming conventions. There is no explicit when-to-use/when-not guidance and no routing away from siblings such as check_required_fields, which an agent equally plausibly might pick for server.json validation.

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. It discloses that this is a fast, required-fields-only check and gives the return shape {pass, missing}, which is useful. It says nothing about what 'pass' signifies, how 'missing' is structured, or behavior on malformed input.

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 'Fast gate' framing, then a terse Args/Returns block with no filler. Efficient, though the docstring-style structure is slightly formulaic for a two-sentence 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 and no annotations, so the description has to do more; it does supply the return keys, which covers the biggest gap. It still leaves the nested server_json shape and the semantics of 'missing' unexplained.

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 0%, so the description must compensate; it does name and gloss both parameters ('server_json: server.json contents', 'spec_version: target spec version'). However the glosses largely restate the schema titles, and for a nested object with additionalProperties the description gives no hint about expected contents or structure.

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

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

The description names a specific verb and resource ('check required fields') and scopes it explicitly with 'only' and 'Fast gate', which implicitly contrasts it with the broader audit_server_json sibling. It stops short of naming that sibling, so an agent still has to infer the split between this and the full audit.

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?

'Fast gate' signals a lightweight pre-check rather than a full validation, which implies usage, but no explicit when-to-use/when-not or named alternative (e.g., audit_server_json) is given. The agent must infer when this is preferable to the sibling tools.

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 burden. It does not disclose whether the template is merely returned or written to disk, whether generation is deterministic, or what 'passing' is validated against. The 'Returns: {template}' line hints at a return value but adds little behavioral context.

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?

Short and front-loaded, with the purpose stated first and args/returns clearly separated. The Args/Returns skeleton is slightly verbose for two parameters but nothing is wasted.

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

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

For a two-parameter template generator with no output schema and no annotations, the description covers the core but leaves gaps: no statement of what 'passing' means, no indication of side effects, and no usage context relative to the audit siblings.

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 0%, so the description must compensate, and it does: 'org: GitHub org slug' and 'slug: Package slug (must end in -mcp by convention)' both add real meaning. The convention constraint on slug is especially valuable, though the placeholder defaults ('your-org') are left unexplained.

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 ... server.json template') with the qualifier 'minimal-but-passing', which is meaningful. It is distinguishable from siblings like audit_server_json and check_required_fields, though it never names an alternative.

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

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

No guidance on when to reach for this generator versus the audit/check siblings, and no prerequisites or sequencing (e.g., generate then audit) are stated. The agent must infer usage entirely from the purpose line.

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 is the only source of behavioral context. It implies a read-only reference lookup and describes what is returned, but it does not mention whether data is static or dynamic, formatting, or any access constraints.

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 efficient sentence with the core action and return value front-loaded. Every phrase contributes directly to understanding the tool's output.

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 zero-parameter lookup tool with no output schema, the description sufficiently explains what the tool returns. It could be slightly more complete by clarifying the shape of the required-fields data or indicating that no input is needed.

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

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

The tool has zero parameters, so the schema imposes no semantic burden. The description's focus on return content is appropriate, and parameter semantics are not applicable.

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

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

The description states a specific verb and resource: returns supported MCP spec revisions and their required fields. It is clear what the tool does, though it does not explicitly distinguish itself from siblings like check_required_fields.

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 return content: an agent can infer this is for looking up spec revisions and required fields. However, there is no explicit guidance on when to use this versus check_required_fields or audit_server_json.

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. It helpfully discloses the return shape ({signed, signature, sealed_at, cert_id}), which signals a sealing/attestation operation. It does not state permission or auth requirements, whether signing is idempotent or irreversible, or what happens on failure.

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 three lines, front-loaded with the core action, then structured Args/Returns blocks. Every line carries information; no filler or restatement of the tool name.

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 one-parameter tool with no annotations and no output schema, the description supplies both the input provenance and the return keys, which covers the essentials. It leaves out auth requirements and failure/verification behavior, but nothing critical to invoking 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 0% and the single parameter is an opaque nested object with additionalProperties=true, so the schema provides essentially no semantics. The description compensates by naming the exact source of the value (audit_server_json output), which is the key ambiguity an agent faces.

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 cryptographic mechanism ('HMAC-sign') plus the resource ('conformity report') and the business goal ('so authors can publish it as evidence'). It is clearly distinct from siblings like check_required_fields or list_spec_versions, though it never explicitly says so.

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 workflow by stating the parameter is the 'Output of audit_server_json()', which tells the agent to run the audit first. However, it gives no explicit when-to-use conditions, no prerequisites (e.g., a report must pass checks before signing), and no when-not-to-use guidance.

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